Webhooks overview

Webhooks let Aigeon push events to your server in real time rather than requiring you to poll. Whenever an email is opened, clicked, bounced, or a contact unsubscribes, Aigeon fires an HTTP POST to the endpoint URL you register — signed, so you can verify it really came from Aigeon.

Setting up a webhook

Open Settings → Webhooks → Create webhook.
Paste your publicly accessible HTTPS endpoint URL.
Select the events you want to receive (or toggle on all events).
Click Create.

Aigeon shows the signing secret once at creation time. Save it in your secret manager — you'll need it to verify incoming payloads.

Payload shape

Every webhook POST body follows this envelope:

{
  "event_name": "emailClick",
  "organization_id": "org_abc",
  "timestamp": 1745000000,
  "data": { ... }
}

event_name — one of the event types from the event catalog.
organization_id — which org the event belongs to.
timestamp — Unix epoch seconds when the event occurred.
data — event-specific payload. Shape varies per event type.

Headers

| Header | Value | | --- | --- | | Content-Type | application/json | | X-Aigeon-Signature | t=<timestamp>,v1=<hmac> | | X-Aigeon-Event | e.g. emailClick |

Retry policy

If your endpoint returns a non-200 response or times out (10-second window), Aigeon retries with exponential backoff: 30 s, 60 s, 120 s. Responses with HTTP 4xx are not retried — they indicate a permanent client-side error.

Managing webhooks via API

You can also create and manage webhooks programmatically:

# List webhooks
curl https://api.aigeon.ai/api/v1/organization/webhooks \
  -H "Authorization: Bearer <jwt>"

# Create a webhook
curl -X POST https://api.aigeon.ai/api/v1/organization/webhooks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My endpoint",
    "url": "https://my.service/aigeon-hook",
    "event_types": ["emailOpen", "emailClick", "emailHardBounce"]
  }'

The create response includes signing_secret — this is the only time it appears. Keep it.