Webhooks
Receive signed events for accounts, leads, messages, campaigns and email, verify their signatures, and handle retries and redelivery.
Webhooks push events to your server as they happen: a reply arrived, an account needs reconnecting, a lead finished a campaign. Each delivery is a signed POST with a JSON body.
Create an endpoint
In the app, open Integrations, add a webhook endpoint with its URL and the events it should receive, and copy the signing secret. Or use the API: Create a webhook endpoint.
- The secret starts with
whsec_and is shown once, when you create the endpoint or rotate its secret. GraphKit stores it encrypted. - An endpoint with no events selected receives every event.
- In production, URLs must use
httpsand resolve to a public address. Private, loopback and link-local addresses are refused, and so are URLs with credentials in them. - Send test delivers a
webhook.testevent to that endpoint only. Test events are never retried.
Events
| Event | When |
|---|---|
account.connected | An account finished connecting and can send. |
account.disconnected | An account was disconnected or removed. |
account.reconnect_required | The network needs the account owner to sign in again (checkpoint, expired session, password change). |
lead.created | A lead was created: import, API, inbox or search. |
lead.replied | A lead in a campaign replied for the first time since enrolling. Sent once per lead per campaign, with campaignId. |
invitation.accepted | A lead accepted a LinkedIn invitation from a connected account. |
message.received | Any inbound message, on any channel. |
message.sent | Any outbound message, from a campaign step or a teammate. |
campaign.started | A campaign was launched or resumed. |
campaign.completed | Every lead in a campaign reached the end or stopped. |
enrollment.completed | A lead finished every step of a campaign. |
enrollment.stopped | A lead left a campaign early: replied, unsubscribed, suppressed, account lost or stopped by hand. |
email.replied | A lead replied to an email from a connected email platform. Counts as a reply for stop on reply. lead.replied is not sent for email replies. |
email.bounced | A connected email platform reported a hard bounce. The lead's email is marked invalid. |
email.unsubscribed | A lead unsubscribed on a connected email platform. GraphKit suppresses the lead on every channel. |
Subscribe to message.received for every inbound message, and to lead.replied for "this lead answered our campaign". List event types returns the catalogue with an example data object for each.
Delivery
POST /hooks/graphkit HTTP/1.1
Content-Type: application/json
User-Agent: GraphKit-Webhooks/1.0
GraphKit-Event: message.received
GraphKit-Delivery: 0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99
GraphKit-Timestamp: 1763200000
GraphKit-Signature: t=1763200000,v1=5f2b9c0e...{
"id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f80",
"type": "message.received",
"apiVersion": "2026-11-15",
"createdAt": "2026-11-15T10:04:05Z",
"organizationId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f60",
"workspaceId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f61",
"data": {
"message": {
"id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f72",
"conversationId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f73",
"channel": "linkedin",
"direction": "inbound",
"body": "Thanks, happy to chat next week.",
"sentAt": "2026-11-15T10:04:05Z"
},
"account": { "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f70", "channel": "linkedin", "displayName": "Alex Rivera" },
"lead": { "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f71", "fullName": "Sam Lee" },
"campaignId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f74"
}
}| Field or header | Meaning |
|---|---|
id | The event id. A redelivery of the same event keeps it: use it to deduplicate. |
GraphKit-Delivery | One event to one endpoint. Stable across retries. |
GraphKit-Event | The event type, also in type. |
apiVersion | The payload version. New fields can appear without a new version. |
Events are delivered at least once and can arrive out of order. Deduplicate on id, and use createdAt or the resource's own timestamps when order matters.
Email event data
The three email.* events share one shape:
{
"email": {
"platform": "warmbly",
"connectionId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f90",
"connectionLabel": "Warmbly",
"address": "sam@northwind.example",
"platformCampaignId": "c_8f2a",
"text": "Thanks, happy to chat next week.",
"occurredAt": "2026-11-15T10:04:05Z"
},
"lead": { "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f71", "fullName": "Sam Lee" }
}Verify the signature
GraphKit-Signature is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of <t>.<raw body> keyed with the endpoint's secret. To verify:
- Compute the HMAC over the raw request body, before any JSON parsing. Re-serialised JSON will not match.
- Compare it with each
v1value in constant time. During a secret rotation the header can carry more than one; accept the delivery if any matches. - Reject timestamps more than 5 minutes from your clock, to stop replays.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/hooks/graphkit', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('GraphKit-Signature') ?? '';
const parts = header.split(',').map((p) => p.split('='));
const t = parts.find(([k]) => k === 't')?.[1] ?? '';
const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
const expected = crypto
.createHmac('sha256', process.env.GRAPHKIT_WEBHOOK_SECRET)
.update(`${t}.`)
.update(req.body)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= 300;
const ok =
fresh &&
sigs.some((s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
if (!ok) return res.status(400).send('bad signature');
const event = JSON.parse(req.body.toString('utf8'));
// Deduplicate on event.id, then handle event.type.
res.sendStatus(204);
});import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["GRAPHKIT_WEBHOOK_SECRET"].encode()
@app.post("/hooks/graphkit")
def graphkit():
header = request.headers.get("GraphKit-Signature", "")
items = [p.split("=", 1) for p in header.split(",") if "=" in p]
t = next((v for k, v in items if k == "t"), "")
sigs = [v for k, v in items if k == "v1"]
body = request.get_data() # raw bytes
expected = hmac.new(SECRET, t.encode() + b"." + body, hashlib.sha256).hexdigest()
fresh = t.isdigit() and abs(time.time() - int(t)) <= 300
if not fresh or not any(hmac.compare_digest(s, expected) for s in sigs):
abort(400)
event = request.get_json()
# Deduplicate on event["id"], then handle event["type"].
return "", 204func graphkitHook(secret string) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
if err != nil {
http.Error(w, "read", http.StatusBadRequest)
return
}
var ts string
var sigs []string
for _, part := range strings.Split(r.Header.Get("GraphKit-Signature"), ",") {
k, v, _ := strings.Cut(part, "=")
switch k {
case "t":
ts = v
case "v1":
sigs = append(sigs, v)
}
}
unix, err := strconv.ParseInt(ts, 10, 64)
if err != nil || math.Abs(float64(time.Now().Unix()-unix)) > 300 {
http.Error(w, "stale", http.StatusBadRequest)
return
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(ts + "."))
mac.Write(body)
want := hex.EncodeToString(mac.Sum(nil))
if !slices.ContainsFunc(sigs, func(s string) bool { return hmac.Equal([]byte(s), []byte(want)) }) {
http.Error(w, "bad signature", http.StatusBadRequest)
return
}
// json.Unmarshal(body, &event), deduplicate on event.ID, then handle event.Type.
w.WriteHeader(http.StatusNoContent)
}
}Responding
Return any 2xx status within 10 seconds. Do the real work after responding, for example by putting the event on a queue. GraphKit does not follow redirects: a 3xx counts as a failure.
Retries and dead letters
A failed delivery (non-2xx, timeout or connection error) is retried with exponential backoff and jitter:
- After failed attempt n, the next attempt waits a random time between half of 1 minute × 3n−1 and that full delay, capped at 12 hours.
- A delivery gets at most 8 attempts, spread over about 18 hours.
- After the last attempt the delivery is dead. It stays in the delivery log and you can Redeliver it by hand.
| Attempt | Waits before it, at most |
|---|---|
| 2 | 1 minute |
| 3 | 3 minutes |
| 4 | 9 minutes |
| 5 | 27 minutes |
| 6 | 81 minutes |
| 7 | about 4 hours |
| 8 | about 12 hours |
The delivery log records every attempt with the request headers and body, the response status, the first 2 KB of the response body and the duration.
Auto-disable
If every delivery to an endpoint fails for 7 days, GraphKit disables the endpoint. The endpoint list and the dashboard show it as disabled with the reason, and the workspace audit log records it. Fix the receiver and re-enable the endpoint; re-enabling clears the failure streak.
Rotating the secret
Rotate the secret from the endpoint in Integrations, or by creating a new endpoint. Copy the new secret into your receiver. Verify against every v1 value in the header, as above, so deliveries signed during the switch are accepted.