Webhooks

Webhooks deliver new entries from your selected sources to an HTTPS receiver. Endpoints are paused until their verification request succeeds.

Verify the signature

Every verification and delivery includes an ISO timestamp in x-watchchangelog-timestamp and an HMAC-SHA256 signature in x-watchchangelog-signature.

v1=hex(HMAC_SHA256(secret, timestamp + "." + raw_request_body))

Calculate the HMAC from the exact unparsed request body, compare it in constant time, and reject timestamps outside your acceptable clock-skew window. Do not parse and reserialize JSON before verifying.

Verification and event shape

Endpoint verification sends {"event":"webhook.endpoint.verify"}. New changelog entries send changelog.entry.created with an event id, source slug, vendor, entry id, title, URL, summary, tags, and publication time.

Delivery events also include x-watchchangelog-id. Persist this id before processing the event and return your previous success for a repeated id.

Retries

A 2xx response marks a delivery complete. Timeouts, connection failures, and non-2xx responses are retried up to three total attempts with increasing delays. Redirects are not followed. After the final failed attempt, the delivery is marked failed for operator review.

Idempotency

Delivery is at-least-once: your receiver can see the same event more than once, especially after a timeout where it processed the body but the acknowledgement was lost. Make handlers idempotent using x-watchchangelog-id, not title or publication time.

Endpoint safety

Use a public HTTPS URL. Local, private-network, credentialed, redirected, and non-public DNS destinations are rejected. Rotating a secret pauses the endpoint until you update and verify your receiver again.