Webhooks

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.