webhook.url with all of that run’s events in items. Runs with no events send nothing.
Request Headers
Payload
The body is limited to 1 MB. Above that, Octen shortens every item’s
full_content and highlight by the same ratio and sets full_content_truncated or highlight_truncated. Get the full content from Get Monitor Run.
metadata and webhook.url use the monitor’s configuration at the time of delivery.
Example for a page monitor with output_schema:
<, >, and & are escaped as \u003c, \u003e, and \u0026. Verify the signature against the raw bytes you receive.
Verify the Signature
Every request is signed with the monitor’swebhook.secret. Verify the signature before processing the payload.
Signature Algorithm
X-Octen-Signature = sha256= + hex(HMAC-SHA256(key, signed payload)), in lowercase hex.
- Signed payload: the value of
X-Octen-Timestamp, then., then the raw request body, such as1794873600.{"event_type":…}. - Key: the 32 bytes decoded from
webhook.secret, not the string itself. Strip theocten_whsec_prefix and decode the remaining 52 characters as base32hex (RFC 4648, alphabet0-9A-V, uppercase, no=padding).
Verification Steps
- Read the raw request body bytes. Don’t parse the JSON and serialize it again, or the bytes change and the signature won’t match.
- Reject the request if
X-Octen-Timestampis more than 300 seconds from your server’s time in either direction. This prevents replay attacks; keep your clock synced with NTP. - Compute the expected signature and compare it with
X-Octen-Signaturein constant time (such ashmac.compare_digestin Python,crypto.timingSafeEqualin Node.js, orhmac.Equalin Go), not with==. - If verification fails, return
401and don’t process the body. Once it passes, deduplicate withX-Octen-Delivery, then return2xxas soon as possible and do slow work after you respond.
Secret Management
webhook.secretis returned only once, in one of three responses: Create Monitor with a webhook, Update Monitor adding a webhook, or Update Monitor with"webhook": {"rotate_secret": true}. Save it right away.- If the secret is lost or leaked, rotate it with
rotate_secret: true; the response returns the new secret. Rotation takes effect immediately with no overlap: later deliveries and pending retries are signed with the new secret, so switch your receiver right away. - Changing only
webhook.urlkeeps the secret. Removing the webhook with"webhook": nulland adding it again generates a new secret.
Test Data
Use the test secret and body below to check your implementation. The body is the example payload above on one line, with no trailing newline. With the current time within 300 seconds of1794873600, verification passes.
Example: Python
Standard library only, Python 3.8+. To usedecode_secret and verify in a framework, read the raw request body, such as request.get_data() in Flask.
OCTEN_WEBHOOK_SECRET='octen_whsec_…' PORT=8000 python3 verify.py
Example: Node.js
Standard library only, Node.js 18+. With Express, read the raw body withexpress.raw({ type: "application/json" }), not express.json().
OCTEN_WEBHOOK_SECRET='octen_whsec_…' PORT=8000 node verify.js
Example: Go
Standard library only, Go 1.20+.OCTEN_WEBHOOK_SECRET='octen_whsec_…' PORT=8000 go run main.go
Respond and Retry
- Return any
2xxto acknowledge. The response body is ignored. Each request times out after 5 seconds, so do slow work after you respond. - Redirects aren’t followed: a
3xxcounts as a failure. - Return
410to stop retrying this delivery. - Any other status code, a timeout, or a connection failure is retried with backoff: each delivery is attempted up to 4 times, with retries about 30 seconds, 2 minutes, and 10 minutes after the first failure.
- After 4 failed attempts or a
410, the delivery isn’t resent. The webhook stays configured, the monitor keeps running, and later runs deliver as usual. Octen also emails the account owner (the organization owner for organization accounts), at most once per monitor every 24 hours. - Undelivered events can still be fetched with List Monitor Events, where
deliveredisfalse(ortrueif that run’s email was sent). Events, runs, and delivery records are kept for 30 days. - Deduplicate retries with
X-Octen-Delivery. If you also pull events, skip ones you’ve already processed byitems[].event_id.
Email Notifications
Withemail set, each run that generates events sends one digest to each recipient, listing up to 10 items. For page monitors, the digest shows the changed fields with previous and current values; without output_schema, it shows a content excerpt and, after the first run, a short summary of the change. For topic monitors, it shows the new results with highlights.