> ## 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 Introduction

> Push email lifecycle events to your agent endpoint instead of polling the API.

Polling `GET /v1/messages` on a timer wastes quota and adds latency to every reply. Webhooks invert the flow: Gork `POST`s a signed JSON event to your HTTPS endpoint the moment something happens — a new inbound email, a confirmed send, a bounce, a complaint, or an unsubscribe.

## How it works

<Steps>
  <Step title="Register an endpoint">
    Subscribe a URL to the events you care about, via the console (**Settings → Webhooks**) or `POST /v1/webhooks`.
  </Step>

  <Step title="Verify the signature">
    Every delivery carries an `X-Gork-Signature` HMAC-SHA256 header. Reject anything that fails verification — see [Verify Requests](/webhooks/verify-requests).
  </Step>

  <Step title="Return 2xx fast">
    Acknowledge receipt with any `200–299` status, then do the slow work (LLM inference, DB writes) asynchronously. Deliveries time out after 10 seconds; anything else is retried — see [Retries](/webhooks/retries).
  </Step>
</Steps>

## Setup

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gork.email/v1/webhooks \
    -H "Authorization: Bearer gork_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://your-agent.com/api/webhooks/gork"
    }'
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.gork.email/v1/webhooks", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GORK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url: "https://your-agent.com/api/webhooks/gork" }),
  });
  const { data } = await res.json();
  // data.secret — save now, it is shown only once
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.post(
      "https://api.gork.email/v1/webhooks",
      headers={"Authorization": f"Bearer {os.getenv('GORK_API_KEY')}"},
      json={"url": "https://your-agent.com/api/webhooks/gork"},
  )
  print(res.json()["data"]["secret"])  # save now, it is shown only once
  ```
</CodeGroup>

Omit `subscribedEvents` to subscribe to the defaults — `["email.received", "email.sent", "email.bounced"]` — or pass an explicit list. Endpoints must be HTTPS URLs. The creation response returns the signing `secret` exactly once; it is never included in `GET /v1/webhooks` listings.

<Warning>
  Save the webhook `secret` immediately. Without it you cannot verify `X-Gork-Signature` headers. If it is lost, generate a new one with `POST /v1/webhooks/{id}/rotate-secret` and update your verifier at the same time.
</Warning>

## Next steps

<CardGroup cols={3}>
  <Card title="Event Types" icon="bolt" href="/webhooks/event-types">
    The five live events and their payload schemas.
  </Card>

  <Card title="Retries" icon="rotate-ccw" href="/webhooks/retries">
    5 attempts, backoff schedule, and the deliveries log.
  </Card>

  <Card title="Verify Requests" icon="shield-check" href="/webhooks/verify-requests">
    HMAC verification in Node.js and Python.
  </Card>
</CardGroup>