Verify webhook signatures
Ottertrail signs each webhook request with the channel’s secret. Check the signature before you act on a request. Then you know that it came from your instance, and that nobody sent an old request again.
The headers
Section titled “The headers”| Header | Value |
|---|---|
Ottertrail-Timestamp |
When this attempt was sent, in Unix seconds |
Ottertrail-Signature |
v1= and 64 lowercase hex digits |
Ottertrail-Delivery |
The delivery’s ID. Retries keep the same ID. |
Ottertrail-Event |
The event type, such as check.down |
The signature is the HMAC-SHA256 of the timestamp, a full stop, and the body exactly as sent. The key is the channel’s secret, as text.
v1=hex(HMAC-SHA256(secret, "<timestamp>.<body>"))The channel’s secret has 43 characters. The owner and admins find it in Settings, on the Notification channels tab, under the channel’s Signing secret: Show shows it, with a button to copy it, and Replace secret makes a new one after asking first. A replaced secret stops working at once, so update your receiver right after you replace it. See Notification channels.
Check a request
Section titled “Check a request”- Read the body as raw bytes, before a JSON parser changes it.
- Read
Ottertrail-Timestamp. Refuse the request when the time is more than a few minutes from your clock. This stops a replay of an old request, even with a valid signature. - Compute the HMAC-SHA256 of the timestamp,
., and the raw body, with the channel’s secret. - Compare your result with the hex after
v1=. Use a comparison that takes constant time. - Answer with a
2xxstatus within 10 seconds. Do slow work after you answer.
To try your receiver, select Send test on the channel. It sends a notification of the type test, and the channel’s Deliveries show how it went.
Node.js
Section titled “Node.js”import { Buffer } from "node:buffer";import { createHmac, timingSafeEqual } from "node:crypto";
const TOLERANCE_SECONDS = 300;
/** * Whether a request came from your Ottertrail instance. * `headers` have lowercase names. `rawBody` is the body as sent, as text. */export function verifyOttertrailWebhook(secret, headers, rawBody, now = Date.now()) { const timestamp = headers["ottertrail-timestamp"]; const header = headers["ottertrail-signature"]; if (typeof timestamp !== "string" || !/^\d+$/.test(timestamp)) return false; if (typeof header !== "string" || !header.startsWith("v1=")) return false; if (Math.abs(now / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false; const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest(); const given = Buffer.from(header.slice(3), "hex"); return given.length === expected.length && timingSafeEqual(given, expected);}Python
Section titled “Python”import hashlibimport hmacimport time
TOLERANCE_SECONDS = 300
def verify_ottertrail_webhook(secret: str, headers: dict, raw_body: bytes) -> bool: """Whether a request came from your Ottertrail instance.
`headers` have lowercase names. `raw_body` is the body as sent. """ timestamp = headers.get("ottertrail-timestamp", "") header = headers.get("ottertrail-signature", "") if not timestamp.isdigit() or not header.startswith("v1="): return False if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS: return False expected = hmac.new( secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, header[3:])package webhooks
import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "math" "net/http" "strconv" "strings" "time")
const toleranceSeconds = 300
// VerifyOttertrailWebhook reports whether a request came from your// Ottertrail instance. rawBody is the body as sent.func VerifyOttertrailWebhook(secret string, header http.Header, rawBody []byte) bool { timestamp := header.Get("Ottertrail-Timestamp") signature, found := strings.CutPrefix(header.Get("Ottertrail-Signature"), "v1=") sent, err := strconv.ParseInt(timestamp, 10, 64) if !found || err != nil || sent < 0 { return false } if math.Abs(float64(time.Now().Unix()-sent)) > toleranceSeconds { return false } given, err := hex.DecodeString(signature) if err != nil { return false } mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(timestamp + ".")) mac.Write(rawBody) return hmac.Equal(given, mac.Sum(nil))}Retries and repeats
Section titled “Retries and repeats”- Any answer other than a
2xxwithin 10 seconds is a failure: a redirect (which is not followed), a4xxor5xx, no answer in time, or a connection that fails. - A failed delivery is tried again after 30 seconds, then after 1, 2, 5, 10, 20, and 20 minutes. That is eight attempts in about an hour. Then it fails for good.
- Each retry has a new timestamp and a new signature, with the same body and the same
Ottertrail-Delivery. - Delivery is at least once. Your receiver can get the same notification two times. Drop a repeat by the body’s
id, or byOttertrail-Delivery.
The body and each event type are described in Webhook payloads.