Webhooks Introduction

Polling GET /v1/messages on a timer wastes quota and adds latency to every reply. Webhooks invert the flow: Gork POSTs 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

Subscribe a URL to the events you care about, via the console (Settings → Webhooks) or POST /v1/webhooks.

Verify the signature

Every delivery carries an X-Gork-Signature HMAC-SHA256 header. Reject anything that fails verification — see Verify Requests.

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.

Setup

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

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

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

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.

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.

Next steps

Event Types

The five live events and their payload schemas.

Retries

5 attempts, backoff schedule, and the deliveries log.

Verify Requests

HMAC verification in Node.js and Python.

Getting Started

AI & Agents

SDKs & Tools

Guides

Webhooks

Security

Account

Solutions

Resources

Webhooks Introduction

How it works

Setup

Next steps

Event Types

Retries

Verify Requests

​How it works

​Setup

​Next steps

Event Types

Retries

Verify Requests

How it works

Setup

Next steps