Using webhooks (experimental)

You can now use webhooks (an experimental feature) in order to get an API call when a certain event happens in your Spendesk account (for Spendesk customers).

Please request access to experimental features from your CSM or via email and create a new API key with experimental scopes:

Using the new API key create a new access token and call POST /webhooks with the URL of your endpoint and the events to subscribe to. One webhook instance is created per event, and the response returns their IDs along with the signing secret:

curl --request POST \
     --url https://public-api.spendesk.com/v1/experimental/webhooks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.masked' \
     --header 'content-type: application/json' \
     --data '{ "url": "https://example.com/spendesk-webhooks", "events": { "payables": ["created", "prepared"], "settlements": ["created"] } }'

We currently support the following events (entity:eventType):

• payables:created
• payables:prepared
• settlements:created

The payload of the event looks like this:

{
    "data":
    {
        "companyId": "7j6mvn11rqf7j5",
        "id": "314a39ea-ada1-57d4-ac08-2632a8cd306e",
        "version": 1
    },
    "event":
    {
        "entity": "settlements",
        "eventType": "created",
        "id": "9ec10a05-f7d7-41dc-b62e-221bcf4a06ee",
        "timestamp": "2024-11-22T08:49:04.509Z"
    }
}

Use the id of the object (in data) to retrieve the latest version of it: either via Get Payable by ID or via Get Settlements.

Each webhook instance is linked to one company ID and to one event. It is not possible to create one webhook instance for multiple company IDs - you will have to create instances for each connected company ID. Subscribing to several events in one request creates one instance per event (within the same company).

For future types of events, keep in mind that the same event can happen on the same resource more than once (e.g. the same payable getting prepared again). Hence we recommend implementing a deduplication check: each event carries a unique event.id, and event.timestamp tells when it was published, which also helps detect events received out of order.

If your endpoint is down for any reason, Spendesk will retry sending the same event on the following schedule:

• 1st level retry - immediately
• 2nd level retry - every 10 minutes for 1 hour
• 3rd level retry - every 2 hours for 3 days

Retries are made on a best-effort basis: exact timestamps are not guaranteed. If the event still fails after the 3rd level, the webhook instance is disabled. Re-enable it with Update a webhook: it resumes from that point, and events published while it was disabled are not sent again — fetch the resources concerned instead.

You can create up to 50 webhook instances for a given company ID. However please do delete the instances you no longer use.

Events will 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 a webhook instance. This can be used to verify the authenticity of the event. When creating a webhook instance, the secret can be provided (at least 32 characters) or a random one will be generated for you; it is returned in the response only once. If this secret needs to be changed the instance will need to be recreated to use the new secret. We recommend letting Spendesk generate it for you.

If you need to allow-list the IP addresses in order to receive incoming API calls, here is the list you need to allow:

• 54.73.124.120
• 54.73.231.189
• 54.195.2.249