Skip to main content
A route with a Webhook action delivers every received message to an HTTPS endpoint of your application. Talario sends a signed POST request with a JSON body and retries until your endpoint confirms it.

​
Endpoints

Manage endpoints in the dashboard under Webhooks. An endpoint URL must:
  • use https on port 443 with a valid, publicly trusted certificate,
  • resolve to a public IP address,
  • not contain a user name, password, query string or fragment.
Talario does not follow redirects. When you change the URL of an endpoint or disable it, open deliveries to it are cancelled; they are not redirected to the new URL. You can retry them afterwards.

​
Deliveries

For every message, recipient and endpoint there is exactly one delivery with a stable delivery_id. A message with two recipients that both match a webhook route therefore results in two deliveries, each naming its own recipient. Each delivery can have several attempts. All attempts and manual retries of a delivery keep the same delivery_id and the same payload version, but get a new timestamp, new signature and new download links.

​
Request

Verify the signature before you process the request.

​
Payload

The body depends on the payload version of the endpoint: Read schema_version in the body to tell the formats apart. A change of the payload version applies to messages received afterwards.

​
Responding

Answer with any 2xx status after you have stored the delivery durably; see Process webhooks reliably. The response body is ignored. Every other outcome is a failed attempt and is retried:
  • any status outside 2xx, including redirects (3xx) and 4xx,
  • a connection that takes longer than 10 seconds to establish,
  • an attempt that takes longer than 120 seconds in total,
  • network and TLS errors.
A single 4xx does not disable your endpoint.

​
Automatic retries

Each delay is extended by a random 0 to 20 %. With 429 or 503, Talario respects a Retry-After header (seconds or HTTP date) of up to 3 hours. Automatic retries end 24 hours after the message was received. The delivery is then failed; the message stays available until expires_at.

​
Manual retries

You can request one more attempt of a failed or cancelled delivery until the message expires: in the dashboard under Inbound, or with the API and a key that may Retry webhooks:
The answer is 202 Accepted; the mail server makes the attempt shortly afterwards. The Idempotency-Key header is required (1 to 255 visible ASCII characters, for example a UUID). Repeating a request with the same key returns the same answer with the header Idempotent-Replayed: true. A manual retry does not start a new 24-hour period of automatic retries. A delivery that your endpoint already confirmed cannot be retried (409 delivery_not_retryable): download the message again instead.

​
Delivery guarantees

Delivery is at least once. A lost response, a timeout after your endpoint stored the delivery or a manual retry can deliver the same delivery again. Your endpoint must recognize repeated deliveries by delivery_id; see deduplication. Deliveries can arrive in any order, and several can arrive at the same time.

​
Delivery state

The API shows the state of each delivery in GET /receiving/messages/{id}: