# Signed webhooks and notifications

Receive governance events, verify authenticity, and handle retries.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/approvals/webhooks

## 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:

```text
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.