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 you CSM or via email and create a new API key with experimental scopes:

Using the new API key create a new access token and POST /webhooks to subscribe to a new event (create a webhook instance).

We currently support the following events:

• 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 or more events. It is not possible to create one webhook instance for multiple company IDs - you will have to create one instance for each connected company ID. The same webhook instance can be registered for multiple events (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 - e.g. if you receive a payable:created event, check that this payable doesn't exist already first.

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

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 or a random one will be generated for you, this will be 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 suggest using a secret of at least 32 characters long and recommend Spendesk generate this 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