Signed webhooks and notifications

Configure an endpoint

Use the console’s Webhooks page to register a destination and supported events, then send a test. Keep the endpoint secret in your server’s secret store. Review delivery attempts in the console before relying on the integration.

Verify the signature

Kastra sends Kastra-Signature in this form:

t=UNIX_SECONDS,v1=HEX_HMAC

The signature is HMAC-SHA256 over the exact bytes of timestamp + "." + raw_request_body, keyed with the endpoint secret. Verify it using a constant-time comparison before parsing or acting on the event. Use the signed timestamp to enforce a freshness window appropriate to your receiver.

Kastra-Event-Id identifies the event for deduplication. A retried delivery must not trigger the same downstream side effect twice. Preserve the raw request bytes: re-serializing JSON changes the signed message.

Keep approvals authenticated

A webhook notification is not an API-key permission to approve a checkpoint. Use the appropriate human authorization and checkpoint contract for any resolution workflow. Do not place a secret in a browser-visible approval URL.

Delivery and other notifications

Treat network failures, retries, and receiver errors as operational states. Monitor failed deliveries and test recovery. Email and in-app notifications have their own delivery behavior; a missing message does not prove that a checkpoint or decision does not exist.