Webhooks

Register an endpoint

For production and shared staging, register an HTTPS URL that Tyxter can reach. For local sandbox work, use the listener below instead of opening a public tunnel.

Webhook registrations remain scoped to the organization, project, and environment of the API key that creates them; an integration spanning several projects still registers one endpoint per project and environment. One receiver URL may be reused across environments, projects, or organizations. Each registration has its own endpoint-specific signing secret, so the receiver must select the secret for the endpoint that sent the request rather than routing or selecting a secret by URL. Patterns are on the Multi-tenant platforms page.

curl https://api.tyxter.com/v1/webhook-endpoints \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://example.com/tyxter-webhook",
    "description": "Production receiver",
    "subscribed_events": [
      "message.sent",
      "message.delivered",
      "message.read",
      "message.failed",
      "message.received"
    ]
  }'

Testing your endpoint

For a registered HTTPS endpoint, POST /v1/webhook-endpoints/{id}/test with an Idempotency-Key creates one signed webhook.test delivery and returns a pending receipt containing webhook_event_id. Store that id, then poll GET /v1/webhook-events/{id} for the terminal status and first-attempt evidence before declaring the receiver ready. The probe ignores subscribed_events, is not a subscribable external event, and does not enter fanout or listen streams. It uses the normal signature, transport, response-evidence, and breaker path: success resets the endpoint breaker, failure increments it, and every test failure is terminal after attempt 1. Each endpoint has five test requests per minute, including authenticated idempotency replays; honor Retry-After and error.retry_after_ms on 429. A disabled endpoint returns 409 webhook_endpoint_disabled: repair the receiver and PATCH it to status active before a fresh probe. Never resend webhook.test: single resend returns 409 webhook_test_not_resendable; bulk resend skips explicit ids and status selections, while event_type webhook.test returns 400 invalid_bulk_webhook_resend. Every fresh probe must use this rate-limited route.

curl -X POST https://api.tyxter.com/v1/webhook-endpoints/$WEBHOOK_ENDPOINT_ID/test \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "idempotency-key: $IDEMPOTENCY_KEY"

Debug failed deliveries

Repeated 401/403 delivery failures usually mean your receiver is verifying the wrong endpoint-specific signing secret. Reusing one receiver URL across environments, projects, or organizations is supported, but the receiver must select the signing secret for the endpoint that sent each request. Debug failed deliveries by inspecting the endpoint delivery attempts and disabled_detail; after correcting receiver verification, re-enable the endpoint with PATCH /v1/webhook-endpoints/{id} and status set to active before sending a fresh test.

Listen locally

The local listener polls GET /v1/webhook-events/listen with a sandbox API key and forwards each event to your localhost receiver with the normal Tyxter signature headers. You do not need to register a normal dashboard webhook endpoint for this local sandbox flow. For inbound tests, filter for message.received; message.created is not emitted.

For container-free signature checks, create a webhook endpoint, then pass its webhook_endpoint_id to GET /v1/webhook-events/listen or GET /v1/webhook-events/listen/{outbox_event_id}. The response includes signature_preview with the exact raw body, timestamp, signature, andtyxter-webhook-* headers generated from that endpoint secret.

From this repo, pnpm sandbox:local-loop runs the full local path once: quickstart diagnostics, inbound simulation, sandbox listen, and optional signed forwarding.

docker run --rm \
  -e TYXTER_API_URL=https://api.tyxter.com \
  -e TYXTER_API_KEY=tx_sandbox_... \
  -e TYXTER_WEBHOOK_FORWARD_URL=http://host.docker.internal:3000/webhooks/tyxter \
  -v tyxter-cli-data:/data \
  ghcr.io/tyxter-dev/tyxter-cli:latest listen

Tyxter CLI lives at github.com/tyxter-dev/tyxter-cli. It persists its local signing secret and cursor in a Docker volume. Run tyxter doctor to check API access and local reachability, then tyxter status to print the signing secret for the SDK verifier below. The sandbox listener can run directly with a sandbox key.

If you are using Codex or Claude Code to test your app, point it at the CLI repo's AGENTS.md or test-sandbox-webhooks skill. It should run the CLI against your app, simulate a sandbox inbound event, and report evidence from both sides.

Event streams and cursors

GET /v1/webhook-events lists durable delivery logs newest first. Page it with limit and starting_after from the previous response next_cursor.

GET /v1/webhook-events/listen streams customer-visible events oldest first for local agents and verifier probes. Page it with limit and cursor from the previous listen response next_cursor. On the first poll, use start_at=oldest to replay retained events or start_at=tail to skip existing retained events.

Honor Retry-After on 429 responses and next_poll_after_ms on successful listen responses before polling again.

curl "https://api.tyxter.com/v1/webhook-events/listen?limit=25&start_at=tail&wait_ms=5000" \
  -H "authorization: Bearer $TYXTER_API_KEY"

Temporary production listen sessions

Production keys can use the same no-public-URL listen stream only inside a short-lived diagnostic session. Create a session, pass its listen_session_id while polling, then disable it when the probe finishes. Sessions are capped at five minutes, rate-limited, limited per environment, and only return events created after the session opened.

SESSION_ID=$(curl https://api.tyxter.com/v1/webhook-events/listen-sessions \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ttl_seconds":300,"reason":"prod receive smoke"}' | jq -r .id)

curl "https://api.tyxter.com/v1/webhook-events/listen?listen_session_id=$SESSION_ID&event_types=message.received&wait_ms=5000" \
  -H "authorization: Bearer $TYXTER_API_KEY"

curl -X DELETE "https://api.tyxter.com/v1/webhook-events/listen-sessions/$SESSION_ID" \
  -H "authorization: Bearer $TYXTER_API_KEY"

Event envelope

Every delivery has the same top-level shape:

{
  "id": "evt_01HZ4...",
  "type": "message.delivered",
  "created_at": "2026-04-27T12:00:00.000Z",
  "environment": "production",
  "trace_id": "trc_01HZ4...",
  "data": {
    "message_id": "msg_01HZ4...",
    "status": "delivered",
    "to": "+5511999999999",
    "from": "pn_01HZ4...",
    "provider_message_id": "wamid.abc",
    "metadata": { "order_id": "ORD-123" }
  }
}

data is event-specific; everything else is fixed. Route by type, log trace_id, dedupe on id. Note that environmentis the kind — sandbox or production— not an id: the envelope carries no organization or project ids. Use the endpoint registration and its endpoint-specific signing secret to select the right receiver configuration; do not infer tenant routing from the receiver URL.

{
  "id": "evt_01HZ5...",
  "type": "message.received",
  "created_at": "2026-05-09T12:00:00.000Z",
  "environment": "sandbox",
  "trace_id": "trc_01HZ5...",
  "data": {
    "message_id": "msg_01HZ5...",
    "status": "received",
    "channel": "whatsapp",
    "sender": { "type": "phone_e164", "id": "+5511999999999" },
    "recipient": { "type": "whatsapp_phone_number", "id": "pn_sandbox_123" },
    "provider_message_id": "sb_wamid_1f7b0c9d4e2a48f3b5c6d7e8f9a0b1c2",
    "metadata": {},
    "content": {
      "type": "text",
      "text": { "body": "ping" }
    }
  }
}

Inbound media

Tyxter delays the customer-visible event while its worker resolves and stores the private provider bytes. On success, media.status is consumed. After bounded retry exhaustion, the event is still delivered with media.status = "failed" and a stable media.failure object, so an inbox can render a durable attachment error instead of waiting forever. Neither form contains a signed URL; mint one only when the user opens or plays the attachment.

For inbound WhatsApp audio, optional media.voiceprojects Meta's voice signal: true identifies a voice note, false an ordinary audio file, and omission a legacy row or absent provider signal.

Branch on data.content.media.status before reading anything else. consumed means the bytes are stored and a download URL can be minted. failed always carries failure.code and failure.message, and it is the only status that carries a failure object. expired means your retention window closed and deleted means the contact was erased; both mean the bytes are gone and no download URL can be minted, while asset_id still identifies the attachment so a replayed event stays matchable to what you already stored.

{
  "type": "message.received",
  "data": {
    "message_id": "msg_01HZ7...",
    "status": "received",
    "channel": "whatsapp",
    "sender": { "type": "phone_e164", "id": "+5511999999999" },
    "recipient": { "type": "whatsapp_phone_number", "id": "123456789" },
    "provider_message_id": "wamid.abc",
    "metadata": {},
    "content": {
      "type": "media",
      "media": {
        "asset_id": "mda_01HZ7...",
        "provider_media_id": "987654321",
        "kind": "audio",
        "voice": true,
        "mime_type": "audio/ogg",
        "byte_length": 18432,
        "filename": null,
        "status": "consumed"
      }
    }
  }
}

Audio transcription is a later, explicit operation. Success emits message.media_transcribed with data.transcript.text, language, duration, provider, model, and the same media_asset_id. Terminal failure emits message.media_transcription_failed with the same error_code as the transcript GET receipt and no speech or provider details. Neither delays nor replaces the playback-ready message.received event.

Existing webhook endpoints are not automatically subscribed when Tyxter adds an event type. Add both transcription events with PATCH /v1/webhook-endpoints/{webhook_endpoint_id} or edit the endpoint in the dashboard.

text is null once contact erasure or your retention window removed the transcribed speech, while status stays "succeeded" and the provider, model, duration, and completion time survive. Treat a null text as erased content, never as a failed transcription.

Interactive inbound selections

The listen API wraps the customer webhook envelope in each item's payload. For interactive replies, read the selection from payload.data.content.interactive, not from payload.interactive or payload.from.

{
  "object": "webhook_event_listen",
  "data": [{
    "id": "out_01HZ6...",
    "type": "message.received",
    "payload": {
      "id": "evt_out_01HZ6...",
      "type": "message.received",
      "trace_id": "trc_customer_123",
      "data": {
        "message_id": "msg_01HZ6...",
        "channel": "whatsapp",
        "sender": { "type": "phone_e164", "id": "+5511988887777" },
        "recipient": { "type": "whatsapp_phone_number", "id": "pn_sandbox_123" },
        "metadata": { "customer_id": "cus_123" },
        "content": {
          "type": "interactive",
          "interactive": {
            "type": "button_reply",
            "button_reply": { "id": "plan:cus_123:pro", "title": "Pro" }
          }
        }
      }
    }
  }],
  "next_cursor": "cur_..."
}

List replies use the same path with interactive.type = "list_reply" and interactive.list_reply.id. Public WhatsApp phone identities normally use strict E.164 with a leading + and preserve every subscriber digit supplied by the provider or sandbox request. If Meta withholds the customer phone on a production inbound message, message.received.data.sender is the explicit unresolved value { type: "phone_e164", id: "" }. Never use that empty id as a recipient or replace it with a synthetic identifier. Internal matching may use separate identity evidence, but it is never substituted into the customer webhook. Correlate sandbox taps with a stable tyxter-trace-id on POST /v1/sandbox/inbound-messages, an app customer id in metadata, or a customer-scoped button_reply.id / list_reply.id.

Template button taps

A tap on a quick-reply button attached to a template message arrives on the same path: content.type is interactive and the selection is at content.interactive.button_reply. You do not need to branch on whether the button came from a template or from an interactive message.

"content": {
  "type": "interactive",
  "interactive": {
    "type": "button_reply",
    "button_reply": {
      "id": "plan:cus_123:pro",
      "title": "Escolher plano"
    }
  }
}

button_reply.id is the quick-reply payload you set on the template button — the value to route on. WhatsApp defaults it to the button label when you do not set one, so give each button a distinct payload (encode your customer or plan key in it) if you need taps to be unambiguous. button_reply.title is the label the customer saw.

Unsupported and unknown inbound types

Not every inbound message is text, media, or interactive. Two other outcomes each carry their own block keyed off content.type. unsupported means the provider refused to deliver what the customer sent — WhatsApp video notes (instant video), polls, and some view-once content, which Meta reports with error 131051 and the fixed explanation "Message type is currently not supported." The bytes never reach Tyxter and never will, so there is no media block on these rows and no attachment to fetch later; the only useful reaction is replying to ask for a regular video, audio, or text. unknown means the provider did deliver the message, in a type Tyxter does not project into a typed field yet — a shared location, contact card, order, or system notice — so the content is there to read: fetch the raw provider envelope with GET /v1/messages/{message_id}. Never ask an unknown sender to resend; only the typed view is missing.

"content": {
  "type": "unsupported",
  "unsupported": {
    "provider_type": "video_note",
    "reason": { "code": 131051, "message": "Message type is currently not supported." }
  }
}

"content": {
  "type": "unknown",
  "unknown": {
    "provider_type": "location"
  }
}

Neither carries text, media, or interactive — the block named by type is the whole content. provider_typeis the provider’s own name for the format and is null when it named none; reason is the provider’s numeric code with its own explanation, and it is null when the provider sent no usable error block. The pair is whole or absent, never half-reported, so a receiver branching on reason.code can trust the message beside it.

The message read carries the same two blocks under the same names: GET /v1/messages/{message_id} and the GET /v1/messages list rows expose unsupported and unknown as nullable sibling fields of media. Like media, they are present without include=payload, so a polling integration classifies these rows on the default list read; media is null on both, and both are null on every other message. For an unknown message, that read is also where the content itself is: the detail response always includes the stored payload, and the list route returns it with GET /v1/messages?include=payload.

Signature verification

Every request carries three headers:

tyxter-webhook-id:         evt_01HZ4...
tyxter-webhook-timestamp:  1714176000
tyxter-webhook-signature:  <hex>

The signature is HMAC-SHA256 over ${timestamp}.${rawBody} using the endpoint's signing secret, hex-encoded. Verify it before trusting the payload.

Using the SDK

import { verifyWebhookSignature } from '@tyxter/sdk-js';

const ok = verifyWebhookSignature({
  secret: process.env.TYXTER_WEBHOOK_SECRET!,
  signature: req.headers['tyxter-webhook-signature'],
  timestamp: req.headers['tyxter-webhook-timestamp'],
  rawBody,              // the exact raw body string — not re-stringified JSON
  toleranceSeconds: 300,
});
if (!ok) return res.status(401).end();

Manual verification (any stack)

signed_payload = "{timestamp}.{rawBody}"
expected       = hex( HMAC_SHA256(signing_secret, signed_payload) )

reject if:
  - tyxter-webhook-signature or tyxter-webhook-timestamp header missing
  - abs(now - timestamp) > 300 seconds
  - timingSafeEqual(expected, signature) is false

Endpoint requirements

Your endpoint must answer 2xx directly: Tyxter never follows redirects, so any 3xx response is a failed delivery attempt (the same security posture as Stripe and Svix), and the attempt log records it as fetch failed: unexpected redirect. The URL must be HTTPS on a publicly resolvable host — localhost, private, and link-local targets are refused, and URLs carrying username:password credentials are rejected at registration. Google Apps Script web apps can never work as webhook endpoints: they answer every POST with a redirect to script.googleusercontent.com and do not expose request headers to doPost, so the tyxter-webhook-signature header cannot be verified there either. Front Apps Script (or anything like it) with a small HTTPS receiver — a Cloud Function or Cloudflare Worker — that returns 200 immediately and forwards the payload onward.

Delivery and retries

• Delivery is at least once and unordered. Do not infer lifecycle order from request arrival time or created_at.
• Any 2xx response is treated as success.
• A non-2xx response, a network error, and a timeout are all failed attempts.
• Failed deliveries follow a fixed retry ladder, not a computed backoff: at most 8 automatic attempts per event, with each retry scheduled 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours, and 24 hours after the attempt before it, so the eighth and last attempt lands about 32.7 hours after the first. The ladder stops at the first 2xx. After the eighth failed attempt the event is terminal with status failed and Tyxter never retries it again on its own; it stays readable as the dead-letter record on GET /v1/webhook-events, which returns the latest five attempts per event while GET /v1/webhook-events/{id} returns the full attempt log, and replaying it takes an explicit POST /v1/webhook-events/{id}/resend or POST /v1/webhook-events/bulk-resend.
• An endpoint that accumulates 20 consecutive failed delivery attempts with no successful delivery in between is auto-disabled: status becomes disabled and disabled_reason becomes unhealthy_consecutive_failures. Its endpoint responses expose disabled_detail with only the triggering last_status_code (or null when there was no response) and failure_class; active, manually disabled, and legacy rows return disabled_detail as null. Tyxter stops sending new events to it, a retry that fires for it afterwards is skipped and leaves that event terminal, and no webhook announces the auto-disable, because a dead endpoint cannot be told it is dead; read the state from GET /v1/webhook-endpoints. Any successful delivery resets the counter, so a transient burst never trips it. Re-enabling is an API operation: PATCH /v1/webhook-endpoints/{id} with status set to active clears the consecutive-failure counter, disabled_reason, and disabled_detail so a repaired endpoint starts clean.
• Every attempt is recorded on the WebhookDeliveryAttempt log.

Resend re-delivers that one event to its own endpoint. A webhook event is recorded per subscribed endpoint, so a resend never fans out to the others. The new attempt is appended to the event's attempt log and continues the ladder rather than restarting it: it takes the next attempt number, so a resend after the eighth attempt runs once and earns no further automatic retries. To replay many events at once, use POST /v1/webhook-events/bulk-resend, which selects by event ids, event type, or delivery status.

Replay protection

• Store processed webhook ids and ignore duplicates.
• Reject timestamps outside a five minute tolerance before checking the signature.
• Keep handlers idempotent: a replayed message.delivered must not double-ship or double-credit anything in your app.

Debug failed deliveries

• Start with GET /v1/webhook-events and filter by event type or delivery status.
• Open the event detail to inspect each delivery attempt, response code, and response body snippet.
• Fix your receiver, then call POST /v1/webhook-events/{id}/resend.
• Use the event trace_id to correlate the webhook with the originating message or batch.

Event catalog