Skip to main content
After each run that generates events, Octen sends one HTTPS POST to the monitor’s 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:
The actual body is one line of JSON, and <, >, 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’s webhook.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 as 1794873600.{"event_type":…}.
  • Key: the 32 bytes decoded from webhook.secret, not the string itself. Strip the octen_whsec_ prefix and decode the remaining 52 characters as base32hex (RFC 4648, alphabet 0-9A-V, uppercase, no = padding).

Verification Steps

  1. 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.
  2. Reject the request if X-Octen-Timestamp is more than 300 seconds from your server’s time in either direction. This prevents replay attacks; keep your clock synced with NTP.
  3. Compute the expected signature and compare it with X-Octen-Signature in constant time (such as hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js, or hmac.Equal in Go), not with ==.
  4. If verification fails, return 401 and don’t process the body. Once it passes, deduplicate with X-Octen-Delivery, then return 2xx as soon as possible and do slow work after you respond.

Secret Management

  • webhook.secret is 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.url keeps the secret. Removing the webhook with "webhook": null and 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 of 1794873600, verification passes.

Example: Python

Standard library only, Python 3.8+. To use decode_secret and verify in a framework, read the raw request body, such as request.get_data() in Flask.
Run: 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 with express.raw({ type: "application/json" }), not express.json().
Run: OCTEN_WEBHOOK_SECRET='octen_whsec_…' PORT=8000 node verify.js

Example: Go

Standard library only, Go 1.20+.
Run: OCTEN_WEBHOOK_SECRET='octen_whsec_…' PORT=8000 go run main.go

Respond and Retry

  • Return any 2xx to 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 3xx counts as a failure.
  • Return 410 to 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 delivered is false (or true if 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 by items[].event_id.

Email Notifications

With email 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.