Webhooks

Symblepay uses webhooks to notify your application when an event happens in your account. They are useful for asynchronous events, e.g. when a payer initiates a trade. When an event occurs, Symblepay collects data about the event, creates an event notification and sends the event webhook endpoint for your user.

When to use webhooks

Some flows in Symblepay occur asynchronous: happening at a later time and not directly in response to your code's execution. With those APIs, Symblepay needs to notify your integration about changes to the state of an object so your integration can take subsequent steps.

The specific actions your webhook endpoint may take differs based upon the event. I.e.:

• Marking an item as being sold when a payer completes a payment to escrow.
• Updating a users profile information when a payout account has been onboarded.

Best practices for using webhooks

Review these best practices to ensure your webhooks remain secure and function seamlessly with your integration.

Event types

You should subscribe to the types of events required by your integration. Listening for extra events will put extra strain on your/our infrastructure and is not recommended.

You can change the events by updating your webhooks configuration.

Requirements and limitations

• Your notification URL must return 2xx HTTP status code within 10s. Otherwise the notification will be retried with exponential backoff.
• Notification attempt schedule:

Attempt number	Time since last attempt	Time since initial notification*
1	-	-
2	30 seconds	30 seconds
3	1 minute	1.5 minutes
4	2 minutes	3.5 minutes
5	4 minutes	7.5 minutes
6	8 minutes	15.5 minutes
7	16 minutes	31.5 minutes
8	32 minutes	63.5 minutes
9	64 minutes	2 hours
10-32	120 minutes	4 - 48 hours

• Approximate values since retries are scheduled after delivery attempt which might take up to 10 seconds.

DANGER

• After all retries have been exhausted the notification is never sent again.
• There is no guarantee of the delivery order.

Check the webhook signatures

All webhook notifications from Symblepay include a x-symblepay-signature header. The value of this header is a HMAC-SHA1 signature generated by concatenating your webhook's notification URL with the body of the request (excluding all whitespaces) and hashing it using the signature key. You can validate the webhook notification by generating the HMAC-SHA1 in your code and comparing it to the signature of the event notification you received. The hash is sent in standard base64 format RFC 4648 §4 (do not mistake with base64url format RFC 4648 §5).

Example pseudocode that generates signature:

Signature generation example

var signature = new HMACSHA1(signatureKey)
    .computeHash(notificationUrl + notificationBody.removeWhitespace())
    .toBase64();

Test webhooks

Use a dedicated Publish Test Notification endpoint to receive test notification. You must have configured a webhook subscription to initiate it.

Create and manage webhook

You can view and manage webhooks in the Symblepay portal

When creating a webhook the URL must be HTTPS and unique per webhook.