Once done setting up a webhook endpoint, you are ready to receive notifications about events. An event occurs when a customer makes a payment. This event will make Speed send you a POST request consisting of a JSON payload.
Now, let’s see what to do to handle such a request optimally.
Read the payload
We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages. The payload will contain an event_type describing the event. All payloads will contain some common properties, but the contents and structure of each payload will vary depending on the object's fields of the event that occurred. Refer to each object's reference document to see which fields will be included.
Analyze events
Speed sends the event data in the request body. Each webhook is structured as an event object with an event_type, id, and related Speed resource nested under data. Once you have the event object, check the event_type to know which event happened. You can use one webhook to handle several different event types at once or set up individual endpoints for specific events.
We do not store any Webhook event notification data that we send, so be sure to capture and store them.
Send 2XX response
Send a successful 200 response to Speed as quickly as possible because Speed retries the webhook if a response isn’t sent.
Webhook retries
If your service has problems handling notifications and there is no response, Speed will retry sending the webhook. These retries will spread over the next 5 days, with varying delays between requests. Individual notifications will have some randomization applied to prevent a large number of concurrent failures from being retried at the same time. Your server should handle deduplication in these cases. The frequency of each message attempt is based on the following schedule, where each period starts following the failure of the preceding attempt.
- Immediately
- 5 seconds
- 5 minutes
- 30 minutes
- 2 hours
- 5 hours
- 10 hours
- 10 hours (in addition to the previous)
- If it doesn't succeed within 5 days of retry, the endpoint will automatically be deactivated.
For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.
If an endpoint is removed or deactivated, the delivery attempts to the endpoint will be deactivated as well.
You can also use the Speed web application to manually retry each message at any time.
Verifying payload
Verify the source of a webhook request to prevent malicious actors from sending fake payloads. To ensure that the requests you're getting at your webhook endpoint are actually coming from Speed, we send the webhook signature header. Learn more about verifying these request signatures.