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:
- Reads the signature from the configured Gitea or GitHub signature header.
- Computes an HMAC SHA-256 value using the shared webhook secret.
- Rejects an invalid signature with
401. - Ignores branches other than
main. - 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.