> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Webhooks and events

> The planned webhooks and events API of Tillcast, signed with Standard Webhooks. Not built yet.

> **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](/api/pagination).

## Event types

| Event                                                                    | When                                                                                                           |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `job.printed`                                                            | The printer confirmed it printed the job                                                                       |
| `job.failed`                                                             | The printer refused the job or reported an error. Carries a reason                                             |
| `job.expired`                                                            | The job's lifetime ended before it was printed. The job says whether the printer had taken it (`delivered_at`) |
| `job.cancelled`                                                          | The job was cancelled                                                                                          |
| `job.delayed`                                                            | The printer has not taken the job 5 minutes after it was created                                               |
| `job.downloaded`                                                         | The printer downloaded the job. Off by default                                                                 |
| `printer.installed`                                                      | The printer connected for the first time                                                                       |
| `printer.connected`, `printer.disconnected`                              | The printer started or stopped reaching Tillcast                                                               |
| `printer.condition_changed`                                              | Cover, paper low, paper out or a jam changed                                                                   |
| `printer.created`, `printer.updated`, `printer.moved`, `printer.deleted` | Printer 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](https://www.standardwebhooks.com/) 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

#### 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.

> **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](/roadmap).