Webhooks

A webhook tells another system, such as your CRM or finance system, the moment something happens in Backed: an application is submitted, a payment is made. Instead of asking the API for changes over and over, your system gives Backed an address, and Backed sends a short, signed message to it for each event you choose. Set webhooks up under Settings > Profile and terms, on the Webhooks tab.

Before you start

You need both the Can access Organisation settings permission and the permission to manage integrations to see the tab and change anything on it.

Each endpoint belongs to an API Credential, so create one first on the API Access tab: see API access. Your system reads the full record through the API with that credential, under the same scopes and rules.

Add an endpoint

Go to Settings > Profile and terms and open the Webhooks tab.
Select New Endpoint.
Enter the Endpoint URL your system receives events at. It must be an https:// address on the public internet: plain HTTP, private, loopback and link-local addresses are refused.
Enter a Description that says which system it is.
Choose the API Credential it belongs to.
Under Events, tick each event type it should receive. Each shows its version and what it means.
Select Create.

The signing secret

When the endpoint is created, Signing secret shows its secret, starting whsec_. Copy it now with Copy signing secret: you will not see it again, and it can't be recovered. Then select I have copied it. Give the secret to your system so it can check that each message really came from Backed.

Check a delivery's signature

Each delivery is an HTTPS POST with a JSON body and these headers:

Backed-Event-Id: the event's id. It is the same on every retry and replay, so your system can ignore a message it has already handled.
Backed-Event-Type: the event type, such as applications.funding_application.submitted.
Backed-Signature: t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256, keyed with your signing secret, of the timestamp, a full stop and the raw body exactly as sent (t.body).

To check a delivery, compute the same HMAC over t, . and the raw body, and compare it with each v1= value. Reject a message whose t is more than five minutes old.

The body names the event's id, type, version, occurred_at and your organisation, and the record it is about: its type, its id and its address in the API. It never carries form answers, bank details or contact details. Read the record through the API to get those.

Event catalogue

Select Event catalogue on the Webhooks tab to see every event type an endpoint can receive, with its version, a description and a sample payload. An endpoint receives only your organisation's events, and only the types it is subscribed to. The developer site has the same catalogue, and a guide to checking signatures: see Developer documentation.

See your endpoints

The list shows each endpoint's URL, Description, API Credential, how many Events it receives, its Status and its Last delivery. The status is one of:

Active: deliveries are being made.
Failing: the latest deliveries are failing, and Backed is retrying them.
Disabled: no deliveries are made until someone enables it again.

Until you add one, the page says No endpoints yet.

Select an endpoint's URL to open its page, with its details, the events it is subscribed to and its Deliveries.

Send a test event

On the endpoint's page, select Send Test. Backed sends one signed webhook.test event straight away and shows the answer on the page: the HTTP status and how long it took, or why it failed. A test is not added to the delivery log. A disabled endpoint can't be tested until you enable it.

The delivery log

Deliveries lists every delivery to the endpoint in the last 30 days, newest first, with its Event, Status, Attempts, Last response code, Duration and when it Occurred. Select Load more to see older ones. A delivery's status is Pending, Retrying, Held, Delivered or Failed.

Events about the same record arrive in the order they happened. While an earlier event for a record is being retried, later ones for that record are Held, then sent in order once it is delivered or has failed.

Retries

A delivery fails if your system answers with anything other than a 2xx status, or does not answer within 10 seconds. Backed tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours. If the last try fails too, the delivery is Failed and is sent again only if you replay it.

After 50 failed deliveries in a row, the endpoint is disabled, and the Administrators who manage integrations are sent an email saying so.

Replay a delivery

Select Replay on a delivery to send it again, with the same Backed-Event-Id. It shows as Pending until it is sent. You can replay a delivery that is Delivered or Failed, from the last 30 days, while the endpoint is enabled.

Disable or enable an endpoint

Select Disable to stop deliveries to an endpoint, and Enable to start them again. Enabling an endpoint clears its count of failed deliveries.

If the API Credential an endpoint belongs to is deleted, its endpoints are disabled at the same moment, and nothing is sent to them until an Administrator enables them again.

Roll the signing secret

If the secret may have been seen by someone who shouldn't have it, select Roll Secret and confirm. The new secret is shown once, with the time the old one stops working. For 24 hours, every delivery carries two v1= signatures, one for each secret, so your system can move to the new secret without missing a message.

Edit or delete an endpoint

Select Edit to change the endpoint's URL, description or events, then Save. Its API Credential can't be changed: create a new endpoint instead.

Select Delete and confirm to delete the endpoint. It stops receiving events and its delivery log is removed. This can't be undone.