Webhooks and events
Webhooks and the events API are not built. Today you read the state of a job with GET /v1/jobs/{job} and GET /v1/jobs, and in the dashboard’s job lists. This page describes the planned design. Names, limits and event types can change before release.
What you will get
- Webhook endpoints. You register an HTTPS URL and the event types you want. Up to 10 endpoints per organization. You can filter to some customers or locations.
- A signing secret that starts with
whsec_, shown once when the endpoint is created. - Events API.
GET /v1/eventsreturns the same events, so a system that cannot receive webhooks can read them in order, and any system can catch up after an outage. It uses the usual pagination.
Event types
The list can change before release. Barcode scans are ignored on purpose.
Signatures
Webhooks follow the Standard Webhooks specification, so you can verify them with an existing library in most languages.
- Headers:
webhook-id,webhook-timestampandwebhook-signature. - Reject a timestamp more than 5 minutes off.
- After you rotate a secret, both secrets sign for 24 hours, so you can switch without downtime.
Delivery
At least once
A receiver can get the same event twice. Deduplicate by webhook-id.
Answer fast
Answer with a 2xx status within 15 seconds. Redirects are not followed.
Retries
A failed delivery is retried with growing waits for about 3 days. An endpoint is disabled at once if it answers 410 Gone, and after 5 days in which every delivery failed. Your technical contact gets an e-mail.
Test and replay
A test button sends a ping event. A replay resends events and keeps their webhook-id.
Delivery log
The log of attempts is kept for 30 days. It holds time, HTTP status, duration and error class, never response bodies.
Only HTTPS on port 443
Tillcast refuses to deliver to private or internal addresses.
Anything free-form you attach to a job, such as a client_reference_id or metadata, is stored with the job history, and will be sent in webhooks.
Verification helpers for TypeScript and Python are planned as small separate packages around the Standard Webhooks libraries. See the roadmap.