Webhooks
Listen for webhook events
Webhooks enable Stenn to send instant, real-time push notifications to your application on events that occur in your Stenn account. This is especially useful for asynchronous events where the result does not follow immediately after an API call, for example, invoice financing application approval, request for additional documents for buyer limit request, etc.
Notification subscription
You can subscribe to webhook events by registering a notification URL. When one of these events is triggered in your account, Stenn will notify your application. The notifications are sent to your configured webhook endpoint URL, as a JSON payload through HTTP POST.
Respond to webhook events
You must acknowledge the notifications we send you. To acknowledge receipt of an event, your endpoint must return a 200 HTTP status code, when either no answer or another response code is received we will retry. Acknowledge events prior to any logic that needs to take place to prevent timeouts.
The event object
Attribute | Type | Description |
---|---|---|
id | string | Unique identifier for the event object |
type | string | Description of the event (i.e. invoice.approved) |
livemode | boolean | Has the value true if the object exists in live mode or the value false if the object exists in test mode. |
data | hash | Object containing payload associated with the event. |
Tips for using webhooks
Receive events with an HTTPS server
Please use an HTTPS URL for your webhook endpoint for security considerations. Your server must also be correctly configured to support HTTPS.
Retry logic
If your webhook endpoint is unavailable or takes too long to respond, Stenn will resend the notification message several times over the course of three days until a successful response is returned.
Acknowledge events immediately
If your webhook script performs complex logic, it's possible that the script would time out before Stenn sees its complete execution. Ideally, your webhook handling code (acknowledging receipt of an event by returning a 200 status code) is separate from any processing performed for that event.
Handle duplicate events
Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against receiving duplicate events by making your event processing idempotent.
To deduplicate events, please use the id
field sent on the event. Across retry, the same event keeps the same "id".
Order of events
Stenn does not guarantee delivery of events in the order in which they are generated. Your endpoint should not expect delivery of these events in this order and should handle this accordingly. You can also use created
in the event payload for ordering.
Updated 6 months ago