Attio Webhook Receiver
Overview
This skill implements the complete event-delivery boundary: authenticate the exact payload, acknowledge within Attio's delivery window, process at least once safely, and reconcile missed or delayed effects.
Prerequisites
- Public HTTPS receiver and approved webhook secret storage
- Required event types and downstream ownership
- Durable queue and idempotency store
- Replay, dead-letter, and reconciliation procedures
Tool Discipline
Use Read, Glob, and Grep to inspect raw-body middleware, route handling, queues, and deduplication. Use WebFetch only for current official Attio webhook documentation. Use Write or Edit after the event contract and failure policy are confirmed.
Current Contract
- Read
Attio-Signature; legacy deliveries may also exposeX-Attio-Signature. - Compute SHA-256 HMAC over the exact raw UTF-8 request body using the webhook secret and compare hexadecimal signatures safely.
- Return a 2xx quickly after validation and durable acceptance; Attio documents a 5-second timeout.
- Delivery is at least once. Use
Idempotency-Keyfor deduplication. - Attio documents up to 10 retries over roughly three days and a delivery limit of 25 requests per second per target URL; reverify before rollout.
Authentication
Store the webhook secret server-side. Verify the signature before JSON parsing, logging, queueing, or any state change, and support controlled secret rotation.
Instructions
- Capture the raw request bytes before body-parsing middleware transforms them.
- Read the supported signature header, decode the expected hex, and reject malformed or unequal-length values.
- Compute raw-body HMAC and use a timing-safe equal-length comparison.
- Validate the event envelope and reserve
Idempotency-Keytransactionally. - Persist the event to a durable queue, then return 2xx within the timeout.
- Process idempotently with bounded concurrency, explicit dead-letter handling, and redacted telemetry.
- Test valid, invalid, duplicate, reordered, delayed, burst, queue-failure, and secret-rotation cases.
- Reconcile authoritative Attio state so a missed event cannot create permanent drift.
Approval Boundaries
Do not create production subscriptions, rotate secrets, replay events, or mutate downstream customer state without the responsible owner and rollback controls.
Output
Return the subscription scope, signature evidence, acknowledgement path, idempotency design, queue behavior, failure tests, reconciliation procedure, and owners.
Error Handling
| Condition | Response |
|---|---|
| Signature is absent or invalid | Reject without parsing or side effects. |
| Idempotency key already committed | Return success without repeating work. |
| Durable queue is unavailable | Return failure so delivery can be retried. |
| Handler exceeds the timeout | Move work behind the queue and acknowledge earlier. |
Examples
Input:
route=/webhooks/attio; events=record updates; queue=durable
Expected handoff:
hmac=raw-body verified; ack=under-timeout; dedupe=transactional; replay=tested