Webhooks Overview

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 or programmatically via the API:

cURL

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"]
  }'

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`)

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

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

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

Inboxes

Messages

Threads

Domains

Webhooks

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

Subscribed Event Types

Registering a Webhook

Payload Schema (`email.received`)

Security & Verification

Retries & Delivery Guarantees