Allowed Scopes: experimental:webhooks:write
Creates one or multiple webhook instances. Each instance will be linked to a company and a specific event.
Maximum of 50 instances can be configured per company.
Be prepared to handle the same event multiple times. Clients should perform de-duplication on their side to avoid
processing the same event multiple times.
Spendesk will retry sending the event until it receives a 2xx response from the webhook endpoint.
Upon failure the webhook instance will be retried immediately. If this retry fails second level retries will begin,
followed by third level retries if necessary.
Finally if webhook instance is still failing the instance will be disabled.
- 1st level retry - ASAP.
- 2nd level retry - every 10 minutes for 1 hour.
- 3rd level retry - every 2 hours for 3 days.
Spendesk will follow this retry policy on a best-effort basis but exact execution timestamps are not guaranteed. The
payload will include a unique event.id that can be used to deduplicate events. The event.timestamp will be the
time the event published and can also be used to determine if an event has been processed before or is out of order.
Events have lightweight payloads carrying the id of the resource in question. Events should be consumed in real-time
by performing a corresponding GET on the resource in question, ensuring the most up-to-date data is used.
Events will be published to the URL specified in the payload. If you need to allow-list incoming http requests from
Spendesk, you can find the list of IP addresses in "Using webhooks" guide.
Events contain a signature in the header x-spendesk-webhook-signature. It is a HMAC SHA256 hash of the payload
using the secret provided when creating the webhook instance.
This can be used to verify the authenticity of the event. When creating a webhook instance, the secret can be provided
or a random one will be generated for you (it will be returned in the response only once).
If this secret needs to be changed, the webhook instance will need to be recreated to use the new secret.
We suggest using a secret of at least 32 characters long and recommend Spendesk generate this for you.