Skip to main content
To start receiving webhook events, reach out to the customer success team to:
  1. Register the URL of an endpoint to receive webhooks
  2. Receive a secret signing key that will be generated and shared with you, essential for ensuring the authenticity of incoming payloads and preventing malicious requests
Ensure that the URL you specify points to a secure endpoint using HTTPS, and can receive POST requests.
The secret signing key can be rotated on request.
We suggest using a tunneling service such as ngrok to test your webhook implementation.

​
Request Headers

When we send a webhook event, the HTTP request includes three essential headers:
  • webhook-id: An ID that uniquely identifies each message.
  • webhook-timestamp: A Unix timestamp indicating when the event was signed. This timestamp is included in the signature to guard against replay attacks. See Verification for more details.
  • webhook-signature: A list of signatures (HMAC-SHA256) created using a secret signing key, used to validate the authenticity of an event. Typically the signature list consists of only one element, but it can contain any number of signatures. It is formatted as a space-delimited list of signatures and their corresponding version identifiers. See Verification for more details. For example: 
    v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo=

​
Processing Events

The endpoint on your server must be capable of receiving HTTPS POST requests. Respond with a 2xx status code within 15 seconds to confirm receipt. If no 2xx status code is received, the system retries delivery according to this schedule:
  • Immediately
  • 5 seconds
  • 5 minutes
  • 30 minutes
  • 2 hours
  • 5 hours
  • 10 hours
  • Additional 10 hours
After the conclusion of the above attempts the event will be marked as Failed for this endpoint. If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled.

​
Structure of an Event

The event payload of a webhook request sent to the registered endpoint will contain:
  • id: An ID that uniquely identifies each event.
  • type: The type of event that triggered the webhook, for example payment_session.created or payment_session.updated.
  • data: The actual payload, which can be a different object depending on the event type. For example, for payment_session.* events, the payload will always be the payment_session object.