Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tallwatch.com/llms.txt

Use this file to discover all available pages before exploring further.

The webhook channel is the universal escape hatch. If a tool isn’t in our native list, you can integrate it by accepting an HTTPS POST. Tallwatch signs every request with HMAC-SHA256 over the raw body so you can prove the message came from us. This page covers the setup and the high-level shape. Two companion pages go deeper:
  • Payload reference — the exact JSON Tallwatch sends, field by field
  • Signing — verification snippets in Node, Go, Python, and Ruby

​
Before you start

  • An HTTPS URL that accepts a POST request. (HTTP is rejected; we never POST credentials over plaintext.)
  • The ability to read a custom request header — verification happens on the server side, not in the browser.

​
Step 1: Decide your signing secret

Generate a random secret of at least 16 characters. This is shared between Tallwatch and your webhook receiver — both sides must hold it to verify the signature. 
openssl rand -base64 32
Save the output. You’ll paste it into both Tallwatch and your receiver’s environment config.

​
Step 2: Add the channel in Tallwatch

1

Open the channels page

Go to Settings → Alerts → Channels in the dashboard and click Add channel.
2

Pick Webhook

Select the Webhook kind. Name it for the receiver: Datadog incidents, Internal ticketing, OpsGenie via webhook.
3

Paste the URL

Paste your HTTPS endpoint into the Webhook URL field.
4

Paste the signing secret

Paste the secret you generated into the Signing secret field. Tallwatch never displays this back after save — store it in your password manager too.
5

(Optional) Customise the payload

Leave the Payload template field blank to use the canonical JSON shape. Or paste a Handlebars template to control the body shape. See Templates.
6

Save and test

Click Save, then click Send test alert. Your receiver should record one POST with a sample incident payload.

​
What gets POSTed

Every dispatch sends a POST with these headers:
HeaderValue
Content-Typeapplication/json
User-AgentTallwatch/1.0
X-Tallwatch-Signaturesha256=<hex> — HMAC-SHA256 of the raw request body, hex-encoded
X-Tallwatch-EventThe event type (incident.opened, incident.resolved, test)
X-Tallwatch-DeliveryA unique UUID for this delivery (use for dedup on your side)
The body is JSON. If you didn’t set a template, it follows the canonical payload. If you set one, it’s the rendered Handlebars output.
Always verify the signature before processing the body. A spoofed POST from a third party looks identical to a real one if you skip verification. The Signing page has copy-paste verification snippets for Node, Go, Python, and Ruby.

​
Acceptable response

Your receiver should return any 2xx status code. Tallwatch treats anything else as a delivery failure:
  • 2xx: marked as sent. Body is discarded.
  • 3xx: marked as failed. We don’t follow redirects on webhook delivery (avoids redirect loops and SSRF).
  • 4xx: marked as failed, NOT retried. A 4xx means your receiver decided the request was bad — retrying won’t help.
  • 5xx, network error, timeout: marked as failed, retried up to 3 times with exponential backoff. After 3 failures, the dispatch row stays failed and shows on the incident detail page.
Timeout is 10 seconds. If your receiver legitimately needs longer, return 202 Accepted immediately and process the event asynchronously on your side.

​
Custom payload shapes

The default payload is rich and verbose. If your receiver expects a specific shape (Slack, Datadog, custom internal tool), use the Handlebars template editor on the channel form. The full variable set is documented at Templates. A quick example — transform the default payload into a minimal Slack-compatible shape:
Webhook payload template
{
  "text": "{{monitor.name}} is {{incident.status}} in {{join failing_regions ", "}}",
  "channel": "#alerts"
}

​
Troubleshooting

Most common cause: signature verification rejects the request because the secret doesn’t match. Confirm the secret in your receiver’s config exactly matches the one in Tallwatch (no leading/trailing whitespace, no extra newlines).Second most common: you’re verifying the signature against the parsed JSON body rather than the raw request body. Always verify against the raw bytes — see the Signing page.
Status 0 means the request never reached your receiver. Causes:
  • The URL is wrong (typo, dead domain, DNS failure)
  • Your firewall blocks outbound connections from Tallwatch’s IPs
  • TLS handshake failed — usually a self-signed or expired cert on your endpoint
Webhook dispatches that return 5xx retry up to 3 times with exponential backoff (~5 s, ~30 s, ~2 min), then stop. They are NOT requeued via the per-channel rate-limit queue (that queue is for rate-limit suppression, not for retrying real failures).If your receiver keeps returning 5xx, fix the receiver and the next new event will dispatch fine. Failed dispatches in the past stay in the failed state — you can resend them manually from the incident detail page.
The canonical payload always sets every field. If a value is genuinely unknown (e.g. resolved_at on an open incident), the field is null rather than omitted. Check your receiver isn’t filtering nullable fields.If you templated the payload, your template controls the shape — re-check the variable references.

​
Reference

PropertyValue
Channel kindwebhook
Required configurl (HTTPS), signing_secret (≥16 chars)
Optional configpayload_template (Handlebars)
HTTP methodPOST
BodyJSON (canonical or templated)
Signature headerX-Tallwatch-Signature: sha256=<hex>
Timeout10 seconds
Retry policy3 attempts on 5xx / network / timeout, exponential backoff
Rate limit1 per 30 s per channel (queued, not dropped)
User agentTallwatch/1.0