Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

Webhooks

Mail arrives, an event fires, your endpoint is called.

Register an endpoint and we POST every event you subscribe to. The response to this call carries the signing secret, once.

curl https://pidgeon.ai/api/v1/webhooks -H "Authorization: Bearer $PIDGEON_API_KEY" -H "Content-Type: application/json" -d '{
  "url": "https://yourapp.com/webhooks/pidgeon",
  "events": ["message.received", "message.delivered"]
}'

The payload we send

Ids and metadata, never a body. Two reasons: an event is delivered to a server we do not control, and it is kept in a log nothing deletes from. Exchange the id for the content when you need it.

json
{
"id": "evt_9c41b…",
"type": "message.received",
"created_at": "2026-09-14T09:41:02.118Z",
"data": {
  "message_id": "msg_8f21c…",
  "thread_id": "thr_31ba9…",
  "identity_id": "idt_5a7d2…",
  "to": "hello@yourdomain.com",
  "from": "billing@supplier.com",
  "subject": "Invoice 4417",
  "has_attachments": true
}
}

Mail arriving at hello@yourdomain.com produces one of these within seconds. Fetch the message when you want the text — GET /v1/messages/{id} — which keeps the body out of your logs unless you put it there.

Read a message

The other half of the contract. The event gave you an id; this gives you the content, authorised and scoped to your account.

curl https://pidgeon.ai/api/v1/messages/msg_8f21c -H "Authorization: Bearer $PIDGEON_API_KEY"

Before you act on any of it

Verify the signature. An unverified webhook endpoint is an unauthenticated POST that says mail arrived, and acting on that is how you get software any stranger can drive. That is the next page, and it is the one page here worth reading twice.