Receiving Webhooks

You can run up to 3 endpoints, for example production, staging, and a partner system. Every event is delivered independently to each enabled endpoint whose filters match it.

• urlHTTPS only

  Up to 2,048 characters. Must resolve to a public address: localhost, private, and reserved IP ranges are rejected, both when you save and again at delivery time.

• event filters

  Pick which event types this endpoint receives. No selection means all of them.

• signing secretper endpoint

  Each endpoint has its own 64-character secret, shown in the portal and rotatable at any time. See Verifying signatures.

• payload profilefull | minimal

  How much customer data this endpoint receives. See Payload profiles.

• data-sharing declaration

  Before an endpoint can be enabled you declare what the destination system is and why it receives customer messages, and attest to it. The declaration is per endpoint, so a partner system and your own backend each carry their own.

• timeout · attempts

  Response timeout defaults to 10 seconds (3 to 30) and retry attempts default to 6 (1 to 10), each adjustable per endpoint.

{
  "webhooks": {
    "endpoints": [
      {
        "id": 7,
        "name": "Production",
        "url": "https://api.example.com/webhooks",
        "enabled": true,
        "event_filters": ["message.received", "lead.email_captured"],
        "envelope_style": "standard"
      },
      {
        "id": 9,
        "name": "Staging",
        "url": "https://staging.example.com/webhooks",
        "enabled": false,
        "event_filters": [],
        "envelope_style": "standard"
      }
    ]
  }
}

Events arrive as an HTTPS POST with a JSON body, typically within seconds of the event. Any 2xx response inside your endpoint's timeout counts as delivered; anything else is retried on a backoff schedule with ±10% jitter. At the default 6 attempts, retries span roughly 18 hours.

Attempt	Delay after failure
1	immediate
2	~5 seconds
3	~5 minutes
4	~30 minutes
5	~2 hours
6	~5 hours
7+	~10 hours each (if attempts raised above 6)

• delivery idstable across retries

  Every attempt for an event carries the same id (webhook-id, and X-SumGenius-Delivery-Id on legacy-signed deliveries). Deduplicate on it: a retry of something you already processed should be acknowledged with a 2xx and skipped.

• 410 Gone

  Responding 410 stops delivery of that event immediately, no further retries.

POST /webhooks HTTP/1.1
Host: api.example.com
Content-Type: application/json
User-Agent: SumGenius-Webhook/1.0
webhook-id: a9b8c7d6e5f40312a1b2c3d4e5f60718
webhook-timestamp: 1753848000
webhook-signature: v1,K6mGq0XcJ9...

{
  "type": "message.received",
  "timestamp": "2026-07-30T04:00:00+00:00",
  "data": { ... }
}

// queue first, work later
app.post('/webhooks', (req, res) => {
  queue.push(req.body);
  res.sendStatus(200);
});

An event that exhausts its retries (or hits a permanent failure like a 410 or an invalid URL) becomes a dead letter. Nothing is silently dropped: the portal's Delivery Log records every attempt with its HTTP status, a snippet of your endpoint's response, and the request duration.

• Retry

  Re-queue a dead letter for delivery, individually or up to 50 at once. Retried events keep their original delivery id.

• Dismiss

  Acknowledge a dead letter you do not intend to redeliver. It leaves the actionable dead-letter count but stays in the log and still counts in the success-rate stats.

attempt      3
status       503
response     "upstream unavailable"
duration     742 ms
next retry   "in ~30 minutes"

Every delivery is signed with the endpoint's own secret using HMAC-SHA-256. Verify before trusting a request; anyone can POST JSON at a public URL.

Which scheme you have: endpoints created since July 2026 sign in the Standard Webhooks format (webhook-id / webhook-timestamp / webhook-signature headers). Integrations set up before then receive both header sets on every delivery, the standard ones and the original X-SumGenius-* ones, so existing verifiers keep working and you can migrate to the standard check whenever you like.

Standard scheme

• signed string

  webhook-id + "." + webhook-timestamp + "." + raw body

• signature

  "v1," + base64(HMAC-SHA-256(signed string, secret)). The header can hold several space-separated signatures; the delivery is valid if any matches. Your secret is the 64-character string from the portal, used as-is.

• timestamp

  Unix seconds. Reject deliveries older than about 5 minutes to prevent replays.

Legacy scheme

• headers

  X-SumGenius-Signature, X-SumGenius-Timestamp, X-SumGenius-Event, X-SumGenius-Delivery-Id

• signature

  "sha256=" + hex(HMAC-SHA-256(timestamp + "." + raw body, secret))

Always verify against the raw request body, byte for byte, before any JSON parsing, and compare with a constant-time function.

$secret  = getenv('SUMGENIUS_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$id      = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
$ts      = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';

// reject stale deliveries (~5 min)
if (abs(time() - (int)$ts) > 300) { http_response_code(400); exit; }

$expected = 'v1,' . base64_encode(hash_hmac(
    'sha256', $id . '.' . $ts . '.' . $rawBody, $secret, true
));

$valid = false;
foreach (explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '') as $sig) {
    if (hash_equals($expected, $sig)) { $valid = true; }
}
if (!$valid) { http_response_code(401); exit; }

http_response_code(200);  // ack, then process async

const crypto = require('crypto');

app.post('/webhooks',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const id = req.headers['webhook-id'];
    const ts = req.headers['webhook-timestamp'];
    if (Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(400);

    const expected = 'v1,' + crypto
      .createHmac('sha256', process.env.SUMGENIUS_WEBHOOK_SECRET)
      .update(`${id}.${ts}.${req.body}`)
      .digest('base64');

    const valid = (req.headers['webhook-signature'] || '')
      .split(' ')
      .some(sig => sig.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));

    if (!valid) return res.sendStatus(401);
    res.sendStatus(200);  // ack, then process async
  });

$expected = 'sha256=' . hash_hmac(
    'sha256',
    $_SERVER['HTTP_X_SUMGENIUS_TIMESTAMP'] . '.' . $rawBody,
    $secret
);
$valid = hash_equals($expected, $_SERVER['HTTP_X_SUMGENIUS_SIGNATURE'] ?? '');

Each endpoint chooses how much customer data its events carry. The active profile is stamped on every event as meta.payload_profile.

• fulldefault

  Everything: customer display name and username, phone and profile name on SMS and WhatsApp, CRM enrichment (contact_id, tags, stage), conversation assignment, attachment URLs and captions.

• minimal

  Keeps ids and message text for routing; drops the customer fields above (everything except platform_user_id), conversation assignment, and per-attachment url, title, and caption (type and media ids remain).

Not profile-gated, deliberately: message.text_raw, message and delivery ids, the channel sub-blocks, and the lead and appointment blocks. A lead event exists to hand you contact info, so lead payloads are always complete.

{
  "customer": {
    "platform_user_id": "17845629031224067"
  },
  "message": {
    "id": "m_mid.4823",
    "text_raw": "Do you ship to Kyiv?",
    "attachments": [
      {
        "type": "image",
        "media_type": "image/jpeg",
        "media_id": "18043762291",
        "received_at": "2026-07-30T04:00:00+00:00"
      }
    ]
  },
  "meta": {
    "version": "v1",
    "payload_profile": "minimal",
    "generated_at": "2026-07-30T04:00:01+00:00"
  }
}