Webhooks
Get a signed HTTPS request the moment a customer, lead, estimate, job, visit, invoice, or payment changes in Shortcut, instead of polling.
After this page you can subscribe an endpoint of your own to changes in a Shortcut workspace, read what Shortcut sends, and manage the subscription from code.
A webhook is a subscription: an HTTPS URL and the event types it wants, such as invoice.paid or visit.completed. When one of those changes happens, Shortcut sends a signed POST to the URL with the record as GET would return it. Your integration hears about the change within about a minute, without polling.
How it works
You create a webhook with a URL and its event types. Shortcut answers with a signing secret, once.
Shortcut collects changes every minute. For each change a webhook subscribes to, it sends one
POSTwith a JSON event.Your endpoint checks the signature, stores the event, and answers with any
2xxstatus.Anything else is a failed attempt, and Shortcut tries again on a schedule for about 15 hours. See Retries and monitoring.
The event types and their payloads are on Events. Checking the signature is on Verify signatures.
Create a webhook
With the API
Creating a webhook needs a token with webhooks:manage and, for each event family you subscribe to, that family's read scope: invoices:read for invoice.paid, payments:read for payment.recorded. A write scope includes its read scope. The Standard integration preset has both. See Scopes.
curl https://api.shortcutco.com/v1/webhooks \
-X POST \
-H "Authorization: Bearer $SHORTCUT_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: accounting-sync-webhook-1" \
-d '{
"url": "https://hooks.example.com/shortcut",
"description": "Accounting sync: invoices and payments",
"eventTypes": ["invoice.paid", "invoice.voided", "payment.recorded", "payment.reversed"]
}'The secret above is an example; yours is different. Store it where your receiver can read it, such as an environment variable. It appears in this response only: Shortcut never shows it again, and a replay of the request with the same Idempotency-Key returns the webhook without it. If you lose it, rotate the secret.
description is optional, up to 200 characters. eventTypes takes one or more of the 28 types on Events.
In Settings
A company admin can also create and manage webhooks in Settings → API & integrations, on the web. A webhook created there can subscribe to any event type, because an admin can see everything; its read scopes are worked out the same way and stored on it. The Webhooks section lists every webhook in the workspace, whoever created it, and lets an admin create one (the signing secret is shown once), edit, pause, resume, or turn it back on, rotate its secret, send a test event, delete it, and see its latest 50 deliveries with their response codes and retry the ones that failed. When Shortcut support signs in to your workspace to help, it can view, pause, and delete webhooks, and nothing else: it cannot create or change one, see a secret, send a test event, or retry a delivery.
Scopes decide what a webhook receives
Each event family has one read scope:
customer.*
customers:read
lead.*
leads:read
estimate.*
estimates:read
job.*
jobs:read
visit.*
visits:read
invoice.*
invoices:read
payment.*
payments:read
When a webhook is created, or its event types change, Shortcut stores the read scopes of its families as requiredScopes. Every payload it sends is serialized under exactly those scopes, as a token with only them would see the record. A token without one of them is refused with 403 insufficient_scope, and requiredScope names the one it lacks.
To change a webhook later, a token must hold the webhook's requiredScopes (after the change), so a token can never point events it could not read at a URL of its own. The exceptions are pausing and deleting, which need only webhooks:manage, so anyone who manages webhooks can always stop one.
Webhooks belong to the workspace
A webhook is a workspace asset, like a token. It keeps working when the token that created it is revoked, and every token in the workspace with webhooks:manage can see, pause, and delete it. createdVia says whether it was created in Settings (settings) or with a token (api_token).
What Shortcut sends
Each event is one POST with a JSON body:
data.objectis the record when the event is sent, not when it happened. It is serialized by the same code as the resource'sGET, so a parser for the API reads it unchanged. A visit that was deleted, or a payment that was reversed, no longer exists; for those two events the object is a short tombstone with"deleted": true. If the record cannot be read withGETwhen the event is sent, for example because it was deleted since, the event is not sent.Events are signals, not a log. Order is not guaranteed, and an object can be newer than its event. When the order of changes matters, compare
updatedAt, or fetch the record.Each event carries one record. Fetch related records by id, such as the customer of a paid invoice, with the API.
Every type, when it fires, and a full example of each family is on Events.
Headers
Content-Type
application/json
User-Agent
Shortcut-Webhooks/1.0
Shortcut-Event-Id
The envelope's id. The same for every retry of the event and for every webhook that receives it. Drop duplicates by it.
Shortcut-Event-Type
The envelope's type, so you can route before parsing the body.
Shortcut-Delivery-Id
This event's delivery to this webhook. The same on every retry; it matches the id in the deliveries list.
Shortcut-Signature
t=<unix seconds>,v1=<hex HMAC-SHA256>, with a second v1 for 24 hours after a rotation. See Verify signatures.
The signing secret
Every webhook has its own secret, whsec_ followed by 43 characters. Shortcut signs each request with it, and your receiver checks the signature before it trusts the body. Treat the secret as a password: keep it out of source control, logs, and web pages.
Rotate the signing secret
Rotate when the secret may have leaked, when someone who knew it leaves, or when you lost it:
The new secret is returned once. For the next 24 hours, until previousSecretExpiresAt, every request carries two signatures, one per secret, new first, so a receiver that still has the old secret keeps verifying while you deploy the new one. After that only the new secret signs. Only the two most recent secrets ever sign: rotating again within the 24 hours retires the oldest one at once.
Rotating needs the webhook's requiredScopes as well as webhooks:manage.
Statuses
status
What happens to new events
How it gets there
active
Sent.
Created, resumed, or turned back on.
paused
Kept, not sent, for up to 30 days, together with anything still waiting when it was paused. Resuming sends them, about two a minute.
PATCH an active webhook with "status": "paused", or in Settings.
disabled
Dropped. Events that happen while a webhook is disabled are never sent.
Shortcut turns a webhook off after 50 failed attempts in a row, and emails and notifies the workspace's company admins. See Retries and monitoring.
Set a paused or disabled webhook back to active with PATCH. Turning a disabled webhook back on starts its failure count over. A disabled webhook cannot be paused: PATCH with "status": "paused" is refused with 409 state_conflict, so turn it back on first.
Limits and URL rules
20 webhooks per workspace, whatever their status. Creating a 21st is refused with
409 webhook_limit_reached.URLs are at most 2,048 characters, and a
descriptionat most 200 after surrounding spaces are trimmed.The URL must be
httpson the standard port, 443, with no username or password in it.The host name must resolve, and every address it resolves to must be public. Private, loopback, link-local, carrier-grade NAT, multicast, documentation, reserved, and cloud-metadata ranges are refused, for IPv4 and IPv6. So
localhost,10.0.0.5, and a name that points at either are refused.The URL is checked again before every request, and Shortcut connects to the exact address it checked. A URL that later starts resolving to a private address fails at delivery instead of reaching it.
Redirects are not followed. Give the final URL.
A URL that breaks a rule is refused with 400 invalid_webhook_url and param body.url; message says which rule. To receive events on your own computer while you build, see Local development.
Manage webhooks with the API
Every operation needs webhooks:manage.
GET /v1/webhooks
Every webhook in the workspace, newest first. Never more than 20, so the list is not paged.
POST /v1/webhooks
Creates a webhook and returns its secret once. Needs the read scope of each family.
GET /v1/webhooks/{id}
One webhook. The secret is never returned here.
PATCH /v1/webhooks/{id}
Changes url, description, or eventTypes, or sets status to paused or active. Needs requiredScopes unless it only pauses.
DELETE /v1/webhooks/{id}
Deletes the webhook and its delivery history, and returns the deleted webhook. Nothing new is sent; a request already in progress at that moment (at most one per delivery) may still arrive.
POST /v1/webhooks/{id}/rotate-secret
Issues a new secret, returned once. Needs requiredScopes.
POST /v1/webhooks/{id}/test
Sends a signed webhook.test event now and returns the delivery with your endpoint's answer.
GET /v1/webhooks/{id}/deliveries
The webhook's deliveries, newest first, paged, with an optional status filter.
POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry
Sends a failed or exhausted delivery again. Needs requiredScopes.
List the workspace's webhooks:
Pause one while you work on your endpoint, then resume it to send what it held:
Change its event types. Send the whole new list; it replaces the old one, and requiredScopes follows it:
Events already waiting for a type you removed are not sent.
Send a test event:
The test event carries no workspace data. It is sent once, whatever the webhook's status, is never retried, and does not count toward the failures that turn a webhook off, so you can check an endpoint before you resume or turn it back on.
Delete a webhook you no longer use:
Listing deliveries and retrying them is on Retries and monitoring.
Errors
The webhook operations answer with the API's usual error body. The codes you are most likely to meet:
HTTP
code
When
400
The URL is not https on port 443, has credentials in it, does not resolve, or resolves to a private address.
400
An unknown event type, an empty eventTypes, or another field problem; param names it.
403
The token lacks webhooks:manage, or a read scope the webhook's events need; requiredScope names it.
409
The delivery is not failed or exhausted, is being sent right now, or is a test event.
503
Shortcut could not issue a signing secret. Nothing changed. Retry after Retry-After, which is an hour.
Next
Events: every event type, when it fires, and example payloads.
Verify signatures: check
Shortcut-Signaturein Node, Python, Ruby, PHP, and Go.Retries and monitoring: what counts as delivered, the retry schedule, and the deliveries list.
Local development: receive events on your own computer while you build.
Last updated