Dispatches an event notification to a configured webhook endpoint
This webhook is triggered when a significant event occurs within the system that a partner might be interested in. The payload contains details about the event type and the associated data.
Request
The webhook will be sent as an HTTP POST request to the URL configured
for the webhook. The body of the request will be a JSON payload
(application/json) containing an ApiWebhookContainer.
Headers
The following headers will be included in the request, adhering to the Standard Webhooks specification:
content-type: application/json: Indicates the payload format.user-agent: MoonPay-Enterprise-Webhooks/1.0: Identifies the sender. Match on theMoonPay-Enterprise-Webhooks/prefix if you allowlist it.webhook-id: A unique UUID identifying the event. It stays the same across all retries of the same event, so use it to deduplicate.webhook-timestamp: A string representing the Unix timestamp (seconds since epoch) of when the webhook notification was sent.webhook-signature: A signature to verify the authenticity and integrity of the payload. The format isv1=<signature>, where<signature>is an HMAC-SHA256 hash.webhook-signature-v2: A signature that also covers thewebhook-id. The format isv2=<signature>, where<signature>is an HMAC-SHA256 hash. Prefer it overwebhook-signature. Later versions can add space-delimited entries to the same header. Use the entry that starts withv2=and ignore the others.
Signature Verification (v1)
To verify webhook-signature:
- Extract the
webhook-timestampfrom the header. - Extract the
webhook-signaturefrom the header and remove thev1=prefix. - Concatenate the
webhook-timestampstring and the raw request body. - Calculate the HMAC-SHA256 hash of the concatenated string using your webhook’s secret key.
- Compare the calculated hash (hex-encoded) with the signature extracted from the header. They should match.
It is crucial to use a constant-time comparison function when comparing signatures to prevent timing attacks. (See the examples for more details)
Signature Verification (v2)
To verify webhook-signature-v2, follow the same steps with these changes:
- Extract the
webhook-idfrom the header too. - Split the
webhook-signature-v2value on spaces, find the entry that starts withv2=, and remove that prefix. Ignore the other entries. - Concatenate the
webhook-idstring, a dot, thewebhook-timestampstring, a dot, and the raw request body.