# Webhooks

Webhooks allow an external service to deliver a signed event to AeThex.

| Field | Value |
|---|---|
| Documentation status | Active |
| Current uses | Signed deployment events and Discord interactions |
| Last source review | 2026-06-26 |

## Deployment webhooks

The AeThex API currently exposes signed deployment webhook handlers for selected repositories.

The receiver:

1. Reads the signature from the configured Gitea or GitHub signature header.
2. Computes an HMAC SHA-256 value using the shared webhook secret.
3. Rejects an invalid signature with `401`.
4. Ignores branches other than `main`.
5. Acknowledges the accepted event before starting the deployment script.

Deployment webhook URLs and secrets are operational credentials and are not published here.

## Discord interactions

Discord sends interactions to `/discord/interactions`.

The receiver verifies:

- `x-signature-ed25519`.
- `x-signature-timestamp`.
- The raw request body.

Invalid requests return `401`. Valid Discord ping requests receive the required handshake response.

## Receiver checklist

- Read and preserve the raw body when the provider signs raw bytes.
- Verify the signature before processing the payload.
- Compare signatures safely.
- Reject stale timestamps when the provider supports replay protection.
- Return quickly and move long work to a background process.
- Make repeated deliveries idempotent.
- Never log active webhook secrets.
- Rotate secrets after suspected exposure.

## Delivery behavior

Clients should expect:

- Duplicate delivery.
- Out-of-order delivery.
- Network timeout after the receiver accepted the event.
- Provider retries.

Use a provider event ID or another idempotency key when mutating state.

## Related documentation

- [[Discord Integration]]
- [[Authentication]]
- [[Security]]
- [[KAEL Safety]]