Data streams: receive webhooks

​

Before you start

• A callback URL. Give the admin an HTTPS address at a public host name. Nexus refuses an IP address, and Lobyco refuses an address in a private network when the subscription is saved and again on every request.
• An authentication method. Agree with the admin how Lobyco signs in to your endpoint: OAuth 2.0 client credentials, HTTP Basic or custom headers. The admin stores it in Nexus as the subscription’s auth integration. Authentication describes the three types.
• The signing key. Nexus shows it once, when the subscription is saved; get it from the admin. It is a base64 string. Keep it in a secret store, never in source code.
• A durable store. A table or a queue where your endpoint keeps each event before it answers. Lobyco recommends one keyed on the delivery id, as in Use the idempotency key.

​

Handle a delivery

​

The request

POST /webhooks/lobyco HTTP/1.1
Host: cdp.example.com
Content-Type: application/json; charset=utf-8
Authorization: Bearer <access token>
User-Agent: Lobyco-Webhooks/1.0
Accept: */*
x-lobyco-event: offer.redeemed
x-lobyco-webhook-id: 9c36b36d1f50d772916352c6499fd695ebdece031df828e05aa454c02b34e7fe
x-lobyco-timestamp: 2026-09-30T10:00:00.0000000Z
x-lobyco-signature: t=1759226401, v1=<64 lowercase hex characters>

<the event's data, as published, or the JSON of the payload transformation>

​

The body

​

Verify the signature

• What is signed: the text <t>.<webhook id>. followed by the raw request body. <t> is the t value from x-lobyco-signature, and <webhook id> is the x-lobyco-webhook-id header.
• The key: base64-decode the signing key and use the resulting 32 bytes as the HMAC key. Do not use the text of the base64 string.
• The header: t=<unix seconds>, v1=<hex>, with a comma and a space between entries. While the admin rotates the key, the header carries one v1 entry per valid key. Accept the request if any entry matches.

1. Read the raw body before any JSON parsing.
2. Split x-lobyco-signature on commas, trim each part, and read t and every v1 value.
3. Reject the request if t is more than 5 minutes from your clock. Lobyco recommends this replay window but does not enforce one. A retry carries a fresh t.
4. Compute HMAC-SHA256(key, "<t>." + webhook id + "." + raw body) as lowercase hex.
5. Compare it with each v1 value in constant time. Accept the request if one matches.

const crypto = require('node:crypto');

function verifyLobycoSignature(rawBody, header, webhookId, secretBase64, toleranceSeconds = 300) {
  const parts = header.split(',').map((part) => part.trim());
  const t = parts.find((part) => part.startsWith('t='))?.slice(2);
  const signatures = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
  if (!t || !/^\d+$/.test(t) || signatures.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  const key = Buffer.from(secretBase64, 'base64');
  const expected = crypto.createHmac('sha256', key)
    .update(`${t}.${webhookId}.`)
    .update(rawBody)
    .digest();

  return signatures.some((signature) => {
    if (!/^[0-9a-f]{64}$/.test(signature)) return false;
    return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), expected);
  });
}

// Express: keep the raw body, and verify before parsing it.
// app.post('/webhooks/lobyco', express.raw({ type: 'application/json' }), (req, res) => {
//   const ok = verifyLobycoSignature(req.body, req.get('x-lobyco-signature') ?? '',
//     req.get('x-lobyco-webhook-id') ?? '', process.env.LOBYCO_WEBHOOK_KEY);
//   if (!ok) return res.sendStatus(401);
//   // Claim the id, store the event, then:
//   res.sendStatus(202);
// });

import base64, hashlib, hmac, time

def verify_lobyco_signature(raw_body: bytes, header: str, webhook_id: str,
                            secret_b64: str, tolerance_s: int = 300) -> bool:
    parts = [p.strip() for p in header.split(",")]
    t = next((p[2:] for p in parts if p.startswith("t=")), None)
    signatures = [p[3:] for p in parts if p.startswith("v1=")]
    if t is None or not t.isdigit() or not signatures:
        return False
    if abs(time.time() - int(t)) > tolerance_s:
        return False
    key = base64.b64decode(secret_b64)
    signed = t.encode() + b"." + webhook_id.encode() + b"." + raw_body
    expected = hmac.new(key, signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in signatures)

using System.Security.Cryptography;
using System.Text;

public static bool VerifyLobycoSignature(byte[] rawBody, string header, string webhookId,
    string secretBase64, TimeSpan tolerance)
{
    string? t = null;
    var signatures = new List<string>();

    foreach (var part in header.Split(',', StringSplitOptions.TrimEntries))
    {
        if (part.StartsWith("t=")) t = part[2..];
        else if (part.StartsWith("v1=")) signatures.Add(part[3..]);
    }

    if (t is null || signatures.Count == 0 || !long.TryParse(t, out var unixSeconds))
        return false;

    var age = DateTimeOffset.UtcNow - DateTimeOffset.FromUnixTimeSeconds(unixSeconds);
    if (age.Duration() > tolerance)
        return false;

    var key = Convert.FromBase64String(secretBase64);
    var signed = Encoding.UTF8.GetBytes($"{t}.{webhookId}.").Concat(rawBody).ToArray();
    var expected = HMACSHA256.HashData(key, signed);

    foreach (var signature in signatures)
    {
        byte[] given;
        try { given = Convert.FromHexString(signature); }
        catch (FormatException) { continue; }

        if (CryptographicOperations.FixedTimeEquals(given, expected))
            return true;
    }

    return false;
}

​

Test your implementation

​

Rotate the key

1. Add the new key next to the old one, and accept a request that matches either.
2. Remove the old key within 24 hours.

​

Use the idempotency key

1. Verify the signature first. The signature covers the id, so the id on a request that passes the check is genuine. Never record the id of a request that fails it.
2. Claim the id in one atomic write. Insert it into a table keyed on the id, or use a conditional put. If the write succeeds, this is the first copy. If it conflicts, it is a repeat. Do not read first and write later: a second copy can arrive while you still handle the first, for example after a timeout.
3. Answer 2xx to a repeat. Any other answer counts as a failure: Lobyco retries the delivery or sets it aside, as in Failure and edge cases.
4. Do not let the check lose an event. Store the event together with its id and process it afterwards. Or record the id in the same transaction as the work it triggers. If you record the id and the work then fails, the retry is skipped as a repeat and the event is lost.
5. Keep the ids for at least 30 days. Retries run for about 45 hours, and Lobyco Support can resend a set-aside delivery for up to 30 days, with the same id. Expiring ids after 31 days covers both.

​

Handle events out of order

• Events about the same customer normally arrive in the order they happened. A retried delivery can still be overtaken by a later event, and a resend by Lobyco Support can arrive days later.
• Definition events have no order at all. An inbound_api.updated can arrive before the inbound_api.created of the same Inbound API block.
• A member’s loyalty-card events are ordered per card. They can arrive before or after that member’s other events.

• For most events, compare the event’s timestamp.
• For an Inbound API event, compare the time of its own change per triggerId: createdAt, updatedAt, publishedAt, stoppedAt or deletedAt.

​

Recognise test requests

• Test sends a fixed body:
  {"event":"webhook.test","subscriptionId":"<subscription id>","timestamp":"2026-09-30T10:00:00.0000000Z"}
  
• Test payload sends a sample of one of the subscription’s events. It has real field names and made-up values, run through the event’s saved payload transformation. Only the x-lobyco-event header tells it apart from a real event.

​

Secure the endpoint

• Protect personal data. Check the data carried by customer events and Inbound API events. A delivery Lobyco could not deliver is kept, body included, for 30 days.
• Revoke credentials through the admin. To stop Lobyco using a set of credentials, ask the admin to switch the subscriptions to another auth integration, or to disable them. Deleting the integration is not enough: see Manage a subscription.

​

Limits

• No delivery history for you. You cannot see your failed deliveries or request a replay. Lobyco Support handles deliveries that were set aside.
• No automatic pause. A subscription stays enabled even if every delivery fails, until an admin disables it.
• No rate limit per subscription. Lobyco limits how many deliveries run at the same time and honours Retry-After. Answer 429 with Retry-After to slow Lobyco down.
• Managed in Nexus only. There is no API to manage subscriptions.

​

Failure and edge cases

• Set-aside deliveries are kept for 30 days, then deleted. Lobyco Support can resend them once the cause is fixed, with the same x-lobyco-webhook-id.
• Disabling discards waiting deliveries. During an outage, ask the admin to leave the subscription enabled: see Manage a subscription.
• A failed payload transformation sends nothing. When the transformation cannot produce valid JSON for an event, Lobyco sets the delivery aside without calling your endpoint. Ask the admin to fix it, then ask Lobyco Support to resend.

​

Related

• Data streams: set up a subscription — what the admin does in Nexus: events, auth integration, signing key, tests and enabling.
• Events — event types, Data streams availability, timing and JSON Schemas.
• OutboundAPI connection — the auth integration types, and how a campaign calls your system at one chosen step.