Receive webhooks (preview)

Set up your webhook in Tellagen

For example, your team can add each new incident to an internal archive. Tellagen sends the incident to your receiver automatically.

Open Settings → Webhooks in your workspace. Add a name and your receiver's public HTTPS URL, then save the signing secret.

You need permission to manage workspace settings. You do not need an API key for setup in Tellagen.

• Set up and manage webhooks

Prepare your receiver

The receiver needs an HTTPS URL on port 443 that resolves to a public address. Tellagen rejects private addresses, localhost, URL credentials, and URL fragments.

Tellagen does not follow redirects. Use the final destination URL.

Store the signing secret in your receiver configuration. Use it to check each request before you process the event.

Prove receiver consent

A saved URL does not prove that its owner accepts webhooks. Tellagen sends no incident data until the receiver proves possession of its signing secret.

After saving the secret in your receiver, select Verify receiver in Settings → Webhooks. Allow one minute between checks.

Tellagen sends an OPTIONS request to the exact destination URL. The Tellagen-Webhook-Challenge header contains a random 32-byte value in standard Base64.

Return HTTP 204 with a Tellagen-Webhook-Proof header. Calculate HMAC-SHA256 over tellagen-webhook-verification-v1: followed by the exact challenge header.

Use the complete signing secret as the HMAC key, including whsec_. Encode the proof with standard Base64. A simple success response is insufficient.

Keep this handler enabled. Tellagen resolves DNS again for each delivery attempt. Only that attempt uses the same current IP for its check and event request.

Later attempts can use a different address from your load balancer pool. The URL stays unchanged. No permanent IP binding is stored.

The check has a five-second timeout and a 1 KiB response limit. Return an empty body. An invalid proof stops delivery and requires verification again. Connection failures use bounded retries.

Existing webhooks also need this check after the receiver verification update. Earlier queued deliveries are canceled.

import { createHmac } from "node:crypto";

// Call this from your HTTPS server, for the webhook route only.
// Keep your existing signature checks for POST requests.
export function handleVerification(req, res) {
  if (req.method !== "OPTIONS") return false;
  const secret = process.env.TELLAGEN_WEBHOOK_SECRET;
  const challenge = req.headers["tellagen-webhook-challenge"];
  if (!secret || typeof challenge !== "string" ||
      !/^[A-Za-z0-9+/]{43}=$/.test(challenge)) {
    res.writeHead(400).end();
    return true;
  }
  const proof = createHmac("sha256", secret)
    .update("tellagen-webhook-verification-v1:" + challenge)
    .digest("base64");
  res.writeHead(204, { "Tellagen-Webhook-Proof": proof }).end();
  return true;
}

Supported event

incident.created is the only supported event type. An omitted or empty event_types array selects this event. Unsupported event types and duplicate entries return HTTP 400.

Tellagen saves the event with the incident in one database transaction. It creates deliveries only for subscriptions that are active at that time.

A new subscription does not receive earlier events. Tellagen does not send webhooks for incident updates or resolution.

The demo workspace does not send webhook deliveries.

What Tellagen sends

Each request uses Content-Type: application/json. The envelope contains id, type, schema_version, occurred_at, resource, and data.

The event id is a UUID. The schema_version is 1. The occurred_at value is the incident creation time in UTC.

The resource object contains the incident type, numeric ID, permanent reference, and revision. The optional resource.url links to the incident.

The data.incident object is a snapshot at creation. It always contains id, reference, and created_at.

Optional fields are title, service, regions, severity, status, issue_type, and impact_summary. Empty optional fields are absent. The example shows a subset of these fields.

{
  "id": "4e937f42-4f28-4f82-9844-91bb3d521922",
  "type": "incident.created",
  "schema_version": 1,
  "occurred_at": "2026-09-14T09:00:00Z",
  "resource": {
    "type": "incident",
    "id": 42,
    "reference": "payments-api-timeout",
    "revision": 1,
    "url": "https://acme.tellagen.com/incidents/by-reference/payments-api-timeout"
  },
  "data": {
    "incident": {
      "id": 42,
      "reference": "payments-api-timeout",
      "title": "Payments API timeout",
      "created_at": "2026-09-14T09:00:00Z"
    }
  }
}

Signature headers

Tellagen uses HMAC-SHA256. The HMAC key is the UTF-8 byte sequence of the complete secret. The key includes the whsec_ prefix. Each signature uses standard Base64.

The signed message contains the event ID, a period, the timestamp, another period, and the original body bytes.

Retries preserve the event ID and body. Each attempt signs the body with the current timestamp.

Check each request

1. Read the original request body as bytes before any JSON parser changes it.
2. Require webhook-id, webhook-timestamp, and webhook-signature.
3. Reject invalid timestamps and timestamps outside the accepted clock window for your receiver.
4. Join the exact webhook-id, ., webhook-timestamp, ., and original body bytes in that order.
5. Calculate HMAC-SHA256 with the complete secret as the key.
6. Do not remove whsec_ or Base64-decode the secret.
7. Split webhook-signature on spaces to read each v1,<base64> value.
8. Base64-decode each v1 signature value.
9. Compare each signature with the calculated digest through a constant-time comparison.
10. If no signature matches, reject the request.
11. After signature verification, parse the JSON body.
12. Check that the envelope id matches webhook-id.

Accept an event once

Duplicate delivery can occur. Concurrent deliveries can arrive out of order. The receiver controls timestamp acceptance and duplicate detection.

The HTTP client timeout is 10 seconds. Tellagen treats a complete HTTP 2xx response as success.

The response body must not exceed 64 KiB.

1. Use the event id to prevent duplicate processing.
2. Save the verified event to durable storage.
3. After the event is safe in storage, return HTTP 204 with an empty body.
4. Process the saved event asynchronously.
5. For a duplicate event, return HTTP 204 without duplicate effects.

Retries and delivery deadlines

Tellagen retries errors without an HTTP response, such as connection errors and timeouts. It also retries HTTP 408, 425, 429, and 500–599.

Other HTTP errors and redirects end that delivery.

The default retry delay starts at 5 seconds. It doubles after each failed attempt, up to one hour. The schedule has no random jitter.

A positive Retry-After replaces the default delay, up to one hour. Tellagen accepts seconds or a future HTTP date. An invalid, zero, or past value uses the default delay.

Each delivery allows at most eight attempts, including attempts deferred by request limits. Five consecutive receiver failures stop delivery and require verification again.

Each delivery has a deadline 24 hours after Tellagen queues it. Tellagen stops retries at that deadline. A pause does not extend the deadline.

Tellagen retains event snapshots for seven days. This retention does not extend the retry window. The public API has no delivery history or manual replay endpoint.

Request and queue limits

All Tellagen workers share request limits. These limits also apply to checks and retries. If the shared limiter is unavailable, Tellagen sends nothing.

In this preview, receiver checks allow three requests per minute per workspace, hostname, and IP address. The shared limit is 30 checks per minute.

All outbound HTTP requests also have limits: 120 globally, 30 per workspace, and 10 per hostname and IP address per minute.

These fixed windows can allow bursts at window boundaries. Concurrent requests are limited to 16 globally and two per IP address.

A workspace can queue at most 1,000 deliveries. Events that exceed this capacity are skipped. Incident creation continues.

Replace a signing secret

In Settings → Webhooks, open the webhook's actions and select Replace signing secret. Save the new secret in your receiver configuration.

For 24 hours, Tellagen signs with both the current and previous secrets. Your receiver can accept either signature during this period.

Tellagen keeps only one previous secret. Another replacement ends the earlier overlap. Requests already in progress can still use an earlier secret.

• Manage webhook settings

Pause or remove a webhook

Use Settings → Webhooks to pause, resume, or remove a destination. Pausing skips new events. Resuming does not replay events from the pause period.

Queued deliveries can resume before their original deadlines. Removing a webhook cancels queued deliveries and cannot be undone.

A request that Tellagen already sent can still reach your receiver after a pause or removal.

• Manage webhooks with the API

Preview limits

Webhooks are in preview and can change. A workspace can have up to 10 active or paused webhooks. The workspace owns each webhook.