Webhooks Overview

Webhooks stream real-time events from Gork 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.complained`	A recipient flagged the email as spam via Feedback Loop (FBL).

Registering a Webhook

You can register webhooks via the Dashboard or programmatically via the API:

cURL

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

Response

{
  "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"
  }
}

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

Payload Schema (`email.received`)

{
  "event": "email.received",
  "message": {
    "id": "msg_908123acdf",
    "inboxId": "inb_728af980b4e",
    "threadId": "thd_128bca90f4",
    "agent": { "id": "agt_128bca90f4", "name": "Alex (SDR)" },
    "from": { "address": "prospect@acmecorp.com", "name": "Marcus Reid" },
    "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>",
    "attachmentsCount": 0,
    "receivedAt": "2026-09-07T12:34:56.789Z"
  },
  "sender": {
    "kind": "human",
    "confidence": "low",
    "evidence": []
  }
}

sender classifies who is on the other end — human, agent, or automated — based on automation headers such as Auto-Submitted, X-Autoreply, and Precedence, plus out-of-office subject patterns. Use it to branch your workflow: an automated sender is usually an out-of-office reply, not a human waiting for an answer.

Security & Verification

Every webhook request contains the header:

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

See Verify webhook requests for reference implementations in Node.js and Python (plus SDK helpers).

Retries & Delivery Guarantees

If your endpoint returns any HTTP status outside of 200-299, Gork retries delivery using exponential backoff:

Attempt 1: Immediate
Attempt 2: 30 seconds
Attempt 3: 2 minutes
Attempt 4: 10 minutes
Attempt 5: 1 hour

4xx responses are treated as terminal — they are your endpoint’s explicit rejection, so they are not retried. After 5 failed attempts the webhook is logged as failed in your organization dashboard.

​Subscribed Event Types

​Registering a Webhook

​Payload Schema (email.received)

​Security & Verification

​Retries & Delivery Guarantees

Subscribed Event Types

Registering a Webhook

Payload Schema (`email.received`)

Security & Verification

Retries & Delivery Guarantees