> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gork.email/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Subscribe to real-time email lifecycle events with signed payloads and automatic retry backoff.

Webhooks stream real-time events from gork.email directly to your agent endpoints, orchestrators, or serverless functions.

## Subscribed Event Types

| Event             | Description                                                               |
| :---------------- | :------------------------------------------------------------------------ |
| `email.received`  | A new inbound email arrived, was parsed, sanitized, and stored.           |
| `email.sent`      | An outbound email was successfully accepted by the upstream mail server.  |
| `email.bounced`   | An email was rejected by the recipient mail server (hard or soft bounce). |
| `email.complaint` | A recipient flagged the email as spam via Feedback Loop (FBL).            |

## Registering a Webhook

You can register webhooks via the [Dashboard](https://gork.email/dashboard/settings) or programmatically via the API:

```bash cURL theme={null}
curl -X POST https://api.gork.email/v1/webhooks \
  -H "Authorization: Bearer gk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent.com/api/webhooks/gork",
    "subscribedEvents": ["email.received", "email.bounced"]
  }'
```

```json Response theme={null}
{
  "data": {
    "id": "whk_71a09ef2bc14",
    "url": "https://your-agent.com/api/webhooks/gork",
    "secret": "whsec_908fca1289ab74e01923847a...",
    "subscribedEvents": ["email.received", "email.bounced"],
    "createdAt": "2026-09-07T12:00:00.000Z"
  }
}
```

<Warning>
  Save the `secret` immediately. It is only returned once upon creation and is used to compute HMAC-SHA256 signatures.
</Warning>

## Payload Schema (`email.received`)

```json theme={null}
{
  "id": "evt_908123acdf",
  "event": "email.received",
  "timestamp": "2026-09-07T12:34:56.789Z",
  "data": {
    "id": "msg_908123acdf",
    "inboxId": "inbox_728af980b4e",
    "threadId": "thrd_128bca90f4",
    "from": "prospect@acmecorp.com",
    "to": ["alex@outbound.yourdomain.com"],
    "subject": "Re: Partnership proposal",
    "text": "Hi Alex,\n\nWe would love to connect this week.",
    "html": "<p>Hi Alex,<br/><br/>We would love to connect this week.</p>",
    "agentShield": {
      "status": "clean",
      "sanitized": true,
      "injectionsDetected": 0
    }
  }
}
```

## Security & Verification

Every webhook request contains the header:

* `X-Gork-Signature`: `t=1757248496,v1=a987ef...`

See the [HMAC Verification Guide](/security/hmac) for reference implementation in Node.js, Python, and Go.

## Retries & Delivery Guarantees

If your endpoint returns any HTTP status outside of `200-299`, gork.email retries delivery using exponential backoff:

1. Attempt 1: Immediate
2. Attempt 2: 30 seconds
3. Attempt 3: 5 minutes
4. Attempt 4: 30 minutes
5. Attempt 5: 2 hours

After 5 failed attempts, the webhook is logged as `failed` in your organization dashboard.