Webhooks: tell other tools what happened

#What a webhook is

Think of it as your project ringing another service to say what just happened. You give Briks an address (a URL the other tool gave you), choose the events it should hear about, and each time one happens Briks sends a message there. Many automation tools, client list tools and spreadsheet add ons can give you such an address.

Technically, each message is a POST request: a call that carries a body, here written in JSON, a plain text format programs read. The receiving tool reads the body and does what you set it up to do.

record.changed follows changes made in the studio: a record added, edited or deleted in the Database tab, a collection cleared, or the database restored. Records the live site saves by itself, such as a booking request a visitor sends, don't trigger it.

form.received is sent for entries from the preview as well as from production. Each message says which, so the other tool can skip preview entries.

#Limits on each plan

When the day's calls are used up, a delivery isn't sent and is marked Failed with: Today's calls for this project are used up, so this delivery was not sent. Send it again tomorrow.

Once a project has as many webhooks as its plan allows, Add webhook is greyed out and a Get more link beside the count opens the upgrade window, which names the smallest plan with room for another.

#Add a webhook

Each webhook in the list shows its address, note and events, which secret it is signed with (the first few characters), and how the last delivery went. Its switch turns it On or Off, and its three dots hold Send a test event (up to ten an hour, only while it is on), Change, New signing secret and Delete.

#What a delivery looks like

Every delivery has the same three parts: type (the event's code), timestamp (when it happened, in UTC) and data (the details). Here is a form entry:

Each delivery also carries three headers: webhook-id (the message's id), webhook-timestamp (when it was sent, in seconds) and webhook-signature. They follow the open Standard Webhooks format, so tools that understand it can check deliveries for you.

#Check that a delivery is genuine

Anyone can send a message to an address, so the receiving end should check the signature before trusting one. The signature is made with the signing secret that only you and Briks have. Once a project has a webhook, the Webhooks page shows a short code example under Checking a delivery is genuine. In words, the check goes like this:

1. Take the body exactly as it arrived, as text, before reading it as JSON.
2. Join the webhook-id, the webhook-timestamp and the body with full stops between them.
3. Take your secret, drop the whsec_ at the start and decode the rest from base64. That is the key.
4. Sign the joined text with HMAC SHA-256 and that key, write the result in base64, and put v1, in front.
5. The delivery is genuine if that matches one of the space separated values in webhook-signature, and the timestamp is within five minutes of now.

A delivery that is tried again keeps its webhook-id, so the receiver can keep the ids it has handled and skip repeats.

#Deliveries and retries

Deliveries lists every delivery of the last thirty days, newest first. Narrow it with Status and press Show. Click one to see the full message, any error and what the address answered.

Each try waits up to 15 seconds for an answer. If the answer isn't a 2xx, Briks tries again: five tries in all, the first at once and then after about 30 seconds, 2 minutes, 8 minutes and 32 minutes, so roughly 45 minutes from first to last. An answer of 410 (gone) stops the retries at once. Redirects aren't followed, so give the final address.

Once a delivery is Failed or Delivered, Send again sends the same message with the same id, signed afresh. The webhook has to be on.

#Insights and settings

Insights sums up the last thirty days: Deliveries, the share Delivered, Failed after every try (with the number of retries it took), and the Average answer time. Below, By event and By address show where failures gather.

Settings has Download JSON under Download the webhooks, with every webhook's address, events and note. Signing secrets are never included. Its danger zone holds Clear log, which deletes the delivery log and stops any retries, and Delete all, which removes every webhook after you type the project's name. Both are for Owners and Admins.

#Worked example: form entries into another tool

Form entries can't be exported from the studio, so a webhook is the way to keep them in another tool as they arrive. The studio keeps them too: the latest 100 show under Settings, Forms.