Receive webhooks

Webhooks are reference-only notifications: event ID, run ID, status, type, and creation time. Fetch protected output using your authorized server credential. Prompts, results, file content, and secrets do not belong in notification payloads.

Webhook configuration and deliveries are environment-wide administrative metadata, protected by explicit webhooks scopes. A webhook administrator does not gain access to end-user conversation text or files. Resolve a notification to protected content only through a separately authorized actor request. New or changed destinations require operator review before delivery.

Verify before accepting

Read X-Mystro-Timestamp (Unix seconds), X-Mystro-Event-Id, and X-Mystro-Signature (one or two comma-separated v1= hex digests). Compute HMAC-SHA256 with your endpoint secret over timestamp + "." + event_id + "." + raw_body, using the exact raw request body. Reject a timestamp outside a five-minute window. During the 24-hour rotation overlap, the sender includes current and previous signatures. Accept a match against a currently valid verification secret, comparing every supplied digest in constant time. Use constant-time digest comparison and never parse/re-serialize JSON before signature verification.

Persist the event ID and queue local processing before returning success. Events are delivered at least once and may arrive out of order. Deduplicate by ID; fetch current run state when ordering matters.

{"id":"evt_example","run_id":"run_example","type":"run.completed","status":"succeeded","created_at":"2026-09-07T10:00:00Z"}

Delivery recovery

Transient failures retry with exponential backoff and jitter for up to 24 hours. A failed delivery can be inspected and explicitly replayed using a fresh request idempotency key. Replaying delivery does not rerun the agent or repeat its tool writes.

Webhook secret rotation reveals the new secret once and returns rotation metadata: current_version, previous_version and previous_retire_at. The old verification secret remains valid for at most 24 hours. A second distinct rotation during this interval returns 409 rotation_overlap_active; replaying the same idempotency key returns metadata only. If the new-secret response is lost, no replay reveals it. Keep the old verifier during the overlap; pause delivery before its retirement if needed, perform a fresh rotation after the window, and durably store the new secret before resuming. Inspect and replay failed notifications as needed. Never print signatures or secrets into application analytics. Request/body logging must redact credential material.