Skip to main content

Responding

Return any 2xx status within 15 seconds to acknowledge a delivery. Trustware ignores the response body beyond its first 4 KiB, which it keeps for your delivery log. Everything else counts as a failed attempt and is retried: Acknowledge first, then do the work. If processing an event can take longer than a few seconds, record it and return 2xx, then process it in the background. A slow handler that times out gets the same event again later. Don’t return 410 for an event you simply don’t want. It disables delivery for your whole project. Return 2xx and ignore the event instead.

Slowing Trustware down

A Retry-After header on a failed response sets the earliest time of the next attempt. It can be a number of seconds or an HTTP date, and Trustware caps it at 24 hours. A value in neither form is ignored, and the normal schedule applies. A 429 or 503 with no Retry-After follows the normal schedule.

Retry schedule

Each webhook event gets up to 10 attempts: the first right away, then retries after these delays, each counted from the previous failed attempt: Each delay varies by up to 10% either way, so retries from many events don’t all land at once. In total the schedule covers about 3 days. Each attempt gets a new webhook-timestamp and a new signature. The webhook-id, sequence and body stay the same. If every attempt fails, the webhook event is marked failed in your delivery log, and your project’s owners and admins get an email. You can redeliver a failed event once you’ve fixed your handler.

Concurrency

Trustware has at most 5 deliveries in flight to one project’s webhook URL at a time. Deliveries can arrive in parallel and in any order, even for the same route intent, so don’t rely on one finishing before the next starts.

When your webhook URL is disabled

Trustware disables your webhook URL when either of these happens:
  • your endpoint returns 410 Gone to any delivery, including a test event or a redelivery
  • a webhook event uses up all 10 attempts, and your endpoint hasn’t returned a 2xx to any delivery in the last 72 hours
When Trustware disables your URL, your project’s owners and admins get an email, and the dashboard shows why it was disabled. You can also disable it yourself from the dashboard. While your URL is disabled:
  • webhook events are still recorded for every change
  • nothing is sent, and retries that were scheduled are cancelled
  • test events and redeliveries are refused
When you re-enable it, new webhook events are sent again. Events recorded while it was disabled aren’t sent automatically. Use Redeliver undelivered in the dashboard to send every undelivered event from the last 30 days that was recorded after you registered the URL. Because each event keeps its sequence, your handler can apply that backlog late without overwriting newer state.

Retention

Trustware keeps webhook events and delivery attempts for 30 days. After that they leave the delivery log and can’t be redelivered. For anything older, read the route intent from /status.

Limits on test events and redeliveries

Sending test events and redeliveries from the dashboard is limited per project: Over a limit, the dashboard shows an error saying how long to wait. Each limit counts separately, and a request refused for another reason, such as a disabled URL, doesn’t count. These limits apply only to sends you start from the dashboard. Webhook events that route intents fire aren’t limited.

Webhook URL requirements

Trustware checks your URL when you register or change it, and again on every delivery. The URL must:
  • use https, on port 443
  • have a hostname that resolves only to public IP addresses
  • have no username or password, and no #fragment
  • be at most 2,048 bytes long
A hostname that resolves to a private, loopback or link-local address is refused, even if another of its addresses is public. If your hostname later starts resolving to such an address, deliveries to it fail and appear in your delivery log as blocked.