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 https and 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.test event to that endpoint only. Test events are never retried.

Events

EventWhen
account.connectedAn account finished connecting and can send.
account.disconnectedAn account was disconnected or removed.
account.reconnect_requiredThe network needs the account owner to sign in again (checkpoint, expired session, password change).
lead.createdA lead was created: import, API, inbox or search.
lead.repliedA lead in a campaign replied for the first time since enrolling. Sent once per lead per campaign, with campaignId.
invitation.acceptedA lead accepted a LinkedIn invitation from a connected account.
message.receivedAny inbound message, on any channel.
message.sentAny outbound message, from a campaign step or a teammate.
campaign.startedA campaign was launched or resumed.
campaign.completedEvery lead in a campaign reached the end or stopped.
enrollment.completedA lead finished every step of a campaign.
enrollment.stoppedA lead left a campaign early: replied, unsubscribed, suppressed, account lost or stopped by hand.
email.repliedA 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.bouncedA connected email platform reported a hard bounce. The lead's email is marked invalid.
email.unsubscribedA 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 headerMeaning
idThe event id. A redelivery of the same event keeps it: use it to deduplicate.
GraphKit-DeliveryOne event to one endpoint. Stable across retries.
GraphKit-EventThe event type, also in type.
apiVersionThe 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:

  1. Compute the HMAC over the raw request body, before any JSON parsing. Re-serialised JSON will not match.
  2. Compare it with each v1 value in constant time. During a secret rotation the header can carry more than one; accept the delivery if any matches.
  3. 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 "", 204
func 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.
AttemptWaits before it, at most
21 minute
33 minutes
49 minutes
527 minutes
681 minutes
7about 4 hours
8about 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.

On this page