Webhooks
What is a Webhook
A webhook is a mechanism that allows a server to push data to a partner or another server in real-time. Rather than the partner polling for updates, the server sends data to the configured URL when a specific event occurs.
- Event-Driven: The server sends data based on specific events rather than partner requests.
- Server Initiated: The server calls a partner-provided URL to deliver data.
- Asynchronous Communication: Webhooks occur asynchronously as the event happens.
- Automatic Data Push: No need for the partner to request; the data is pushed automatically.
A traditional API endpoint , on the other hand, is a specific URL that a partner can call to interact with a web service. The partner initiates the request, and the server responds with data. This interaction usually follows a request-response model over HTTP/HTTPS.
- Request-Response Model: The partner makes a request, and the server provides a response.
- Partner Initiated: The partner must actively request data or services.
- Common Methods: GET, POST, PUT, DELETE, etc.
- Examples: RESTful APIs, gRPC services, etc.
Configuring Webhook
You can provide two webhook URLs to Redeam: one for production and one for sandbox. These webhooks URL will be configured using the Redeam Notification Registry.
Webhook endpoints must use the HTTPS protocol for security reasons.
If your webhook is functioning normally, it should always return a 200 HTTP status (the response body is irrelevant). Redeam will apply a retry logic for some specific failure cases of non-200 statuses, but ultimately, it is your responsibility to ensure the webhook is working properly.
Webhook Timeouts
Notification requests sent to the webhook by Redeam have a timeout of 60 seconds. You are expected to respond within the timeout. This applies to production and sandbox environments.
Automatic Retries
If Redeam receives one of the specific HTTP error responses below, we will try to send the notification again. Redeam will retry up to 3 times with an increasing delay between each failed attempt.
- 408 Request Timeout
- 425 Too Early
- 429 Too Many Requests
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Duplicate Handling
Due to retries, it's possible that your application receives the same notification more than once. Check the timestamp field of each response to make sure you have the latest data stored.
This scenario would occur when Redeam is retrying one of the failed notifications and another change comes in for the same data so we end up with 2 notifications for the same data.
Out-of-Order Delivery
Related to the above scenario, notifications can also arrive at your application out-of-order. This can be due to issues such as network delays or failures. However, you can determine the order of the events by examining the timestamp field of the notification.
Security
In Notifications APIs, there is a signature object to validate the origin of a notification. The sum can be validated by generating an md5sum using the Notification Rule's SecurityKey. More details in the API documentation.
Redeam is not sharing the specific data change in the notification, you get the message and then need to fetch the information from the existing API endpoints. This adds another layer of security because you, the reseller, needs to call Redeam APIs using your specific authentication keys to retrieve the data.