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 expose X-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-Key for 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

1. Capture the raw request bytes before body-parsing middleware transforms them.
2. Read the supported signature header, decode the expected hex, and reject malformed or unequal-length values.
3. Compute raw-body HMAC and use a timing-safe equal-length comparison.
4. Validate the event envelope and reserve Idempotency-Key transactionally.
5. Persist the event to a durable queue, then return 2xx within the timeout.
6. Process idempotently with bounded concurrency, explicit dead-letter handling, and redacted telemetry.
7. Test valid, invalid, duplicate, reordered, delayed, burst, queue-failure, and secret-rotation cases.
8. 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

Resources

• Skill-specific official documentation
• Webhooks
• REST API overview