Skip to navigation

Webhooks and events

Planned. Tillcast will tell your system when a job or a printer changes.
View as Markdown
Planned. Not live.

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/events returns 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

EventWhen
job.printedThe printer confirmed it printed the job
job.failedThe printer refused the job or reported an error. Carries a reason
job.expiredThe job’s lifetime ended before it was printed. The job says whether the printer had taken it (delivered_at)
job.cancelledThe job was cancelled
job.delayedThe printer has not taken the job 5 minutes after it was created
job.downloadedThe printer downloaded the job. Off by default
printer.installedThe printer connected for the first time
printer.connected, printer.disconnectedThe printer started or stopped reaching Tillcast
printer.condition_changedCover, paper low, paper out or a jam changed
printer.created, printer.updated, printer.moved, printer.deletedPrinter lifecycle
customer.*, location.*Created, suspended, reactivated, deleted

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-timestamp and webhook-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

A receiver can get the same event twice. Deduplicate by webhook-id.

Answer with a 2xx status within 15 seconds. Redirects are not followed.

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.

A test button sends a ping event. A replay resends events and keeps their webhook-id.

The log of attempts is kept for 30 days. It holds time, HTTP status, duration and error class, never response bodies.

Tillcast refuses to deliver to private or internal addresses.

Do not put guest data in metadata

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.