Setting Up Webhooks
1
Create a Webhook Endpoint
Set up an HTTPS endpoint on your server to receive webhook payloads.
2
Register the Webhook
Use the Partner API to register your webhook URL.
3
Verify Signatures
Validate incoming webhook signatures to ensure authenticity.
4
Process Events
Handle the webhook payload and update your application state.
Registering a Webhook
Webhook Events
Webhook Payload
Each webhook delivery includes a JSON payload with the event details:Signature Verification
Every webhook request includes aX-Hypermid-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.
Managing Webhooks
List Webhooks
Delete a Webhook
Best Practices
-
Respond quickly — Return a
200status within 5 seconds. Process the event asynchronously if needed. -
Handle duplicates — Webhooks may be delivered more than once. Use the
transactionIdororderUidto deduplicate. - Use HTTPS — Webhook URLs must use HTTPS for security.
- Implement retry logic — If your endpoint returns a non-2xx status, Hypermid will retry the delivery with exponential backoff.
- Log everything — Store the raw webhook payload for debugging purposes.
- Keep your secret safe — Store the webhook signing secret securely and rotate it periodically.