API & developer

Webhooks.

Subscribe to pipeline events. Signed payloads. At-least-once.

Webhooks fire when state changes. They are signed with HMAC-SHA256 using a per-endpoint secret. Verify the signature on every receive.

Events

Event	Fires when
`lead.qualified`	A lead passes qualify()
`lead.rejected`	A lead fails any stage with a non-retry reason
`draft.ready`	An email draft is awaiting review
`draft.approved`	A reviewer approves a draft
`draft.rejected`	A reviewer rejects a draft
`send.completed`	The email is accepted by your relay
`reply.received`	track() classifies a reply

Payload shape

POST https://you.example.com/paitho
        X-Paitho-Signature: t=1745588901,v1=...
        Content-Type: application/json

        {
          "event": "draft.ready",
          "id": "evt_01HX...",
          "occurred_at": "2026-04-25T14:08:21Z",
          "data": { "lead_id": "lead_01HX...", "draft_id": "drf_01HX...", "review_url": "https://app.paitho.ai/..." }
        }

Retries

We retry non-2xx responses with exponential backoff for 24 hours, then dead-letter the event. Dead letters are visible at Workspace → Settings → Webhooks → Dead letters and replayable from there.