Access · Webhooks
Get a web address that another service calls when something happens
A webhook is a web address that another service sends a message to when something happens: a payment, a form sent, an order placed, a new message. The system makes one in one line, keeps every delivery whole in the Ledger, and can run an action when one arrives.
Making a webhook needs a key from us. Sending to it needs only its address.
- 10:02:14Order placedOrder 4821 · Dana ReyesKept whole
- 10:02:15Order placedSame delivery ID as 10:02:14Duplicate
- 10:07:51Payment refundedOrder 4790 · ran: text the customerKept · ran an action
- 10:15:03Order shippedOrder 4821 · tracking attachedKept whole
Each delivery is one Ledger entry, with every header and the whole body.
An illustration. The business and the people are made up.
How much detail
Developers: choose “For your developer” for the address that runs an action on each delivery.
Made in one line
Name it, and the answer is its address
Paste the address into the other service’s webhook settings: a payment service, a shop, a form builder, a code host, anything that can send a web request.
- 1
Ask for a webhook, with a name
By text to us, or with one request.
- 2
Get its address
https://miscsubjects.com/hook/ followed by hk_ and 12 letters and digits.
- 3
Paste it into the other service
From then on, that service calls it when something happens.
The one line
curl -X POST https://miscsubjects.com/api/objects/webhook \
-H "x-sheets-key: YOUR_KEY" \
-H "content-type: application/json" \
-d '{"name": "Shop orders"}'YOUR_KEYis a placeholder: you get a key from us. The answer gives the webhook’s address, and the requests that read its deliveries.
Every delivery is kept
Every delivery is a Ledger entry, with the whole request
- Each delivery is written down whole, as it arrived: every header and the whole body.
- If the service sends the same delivery twice, the second is marked as a duplicate. The system reads the delivery ID that GitHub, Shopify, Linear and others put in their headers, or one in the body.
- Nothing about a delivery is summarised away: what arrived is what is kept.
When something is missing, you can see whether the other service ever sent it, and exactly what it sent.
A duplicate is kept too, and marked, so a repeat can be told apart from a new event, and the second copy is still on the record.
The delivery ID is the first of: the headers webhook-id, svix-id, X-GitHub-Delivery, X-Shopify-Webhook-Id, Linear-Delivery, X-Delivery-Id; a path you set on the webhook (a body path, or header:<name>); then the body’s event_id, delivery_id, webhook_id, id, data.id.
curl -X POST https://miscsubjects.com/hook/HOOK_ID \
-H "content-type: application/json" \
-d '{"id": "example-delivery-1", "hello": "world"}'Run an action
A delivery can run an action
Add an action’s name to the end of the webhook’s address. Each delivery then runs that action, with the delivery’s body as its inputs, the same way as any other request.
When the shop sends
Payment refunded, order 4790
The system runs
Text the customer from your number
And writes down
The delivery, the text sent and the answer, in the Ledger
An illustration. The business and the people are made up.
The same permissions apply as for any other request: an action outside its limits is refused, and the refusal is written down. Choose “For your developer” to see the address.
# a delivery to this address runs the action ACTION_NAME, with the body as its inputs
POST https://miscsubjects.com/hook/HOOK_ID/ACTION_NAME
content-type: application/json
{"to": "Dana", "text": "Your refund is on its way."}HOOK_IDis your webhook’s id; ACTION_NAME is an action’s name from the Directory.
Keep it private
The address is the key, so give it only to the service that needs it
Knowing the address is enough to send
There is no password on a delivery. Give the address only to the service that calls it.
Switch it off
A webhook that is switched off refuses every delivery. The refusals are written down too.
Opening it shows only its name
Opening the address in a browser shows the webhook’s name and whether it is on. It shows no deliveries.
Reading deliveries
Deliveries are read from the Ledger, or from the command line
Live, read from this site just now.
# every delivery, whole, with duplicates marked GET https://miscsubjects.com/api/ledger?event=webhook%20delivery&limit=500 x-sheets-key: YOUR_KEY # or, from the command line misc hook list misc hook deliveries
Get a webhook.
Text us which service will call it and what should happen when it does. You get the address, and a key to read its deliveries.