Receive signed webhooks at your own endpoint

The receiver must be reachable on the public internet over HTTPS on port 443, with no username or password in the address. Registration rejects plain HTTP, credentials, a non-default port, and a private or loopback IP address written as a literal. A hostname is not resolved at registration: https://localhost/hook or a name that points at a private network passes registration and then fails at delivery as a permanent Action needed row. Redirects are never followed.

Read the raw request body, verify the signature, durably store the Idempotency-Key together with the work or a queued job, and return a 2xx response within 10 seconds; the connection is cut at exactly 10 seconds and the attempt counts as a timeout. Do heavier work after responding. 408, 425, 429, 5xx, timeouts, and most 3xx responses are retried; 301 and 308 are permanent because the address itself moved, and any other 4xx is permanent.

During development, expose a local server through one HTTPS tunnel. Use either Cloudflare or ngrok below. Register its public URL in the next section, then install the returned secret before sending a test. Keep signature verification enabled.

# Cloudflare: prints a https://<random>.trycloudflare.com address
cloudflared tunnel --url http://localhost:3000

# ngrok: prints a https://<random>.ngrok-free.app address
ngrok http 3000

Create a live API key with Manage notification endpoints and Read submissions using Create API keys. Call GET /activations as shown there and copy your experience’s UUID id.

Replace the example URL and UUID below with your receiver and experience. This example sends finished-photo events for one experience. Choose submission.created for guest details before processing, submission.completed for finished photos without a review requirement, or submission.approved for approved photos. Use the consent policy you chose above. Omit experience_ids only when you intend to receive the whole account.

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer ${SNAPBAR_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/snapbar",
    "event_types": ["submission.completed"],
    "consent_policy": "marketing_consented",
    "experience_ids": ["2f5c1a8e-7d3b-4e1f-9a6c-0b8d4e2f1a37"]
  }' \
  https://integrations.snapbar.com/v1/webhook-endpoints

The 201 response includes signing_secret once, prefixed whsec_. Store it as a credential next to the endpoint id and install it in your receiver. Registration activates the endpoint immediately; use a rehearsal experience until verification passes. If the response is lost, list endpoints with GET /webhook-endpoints before registering again, then delete the orphan and re-register to get a new secret.

{
  "id": "9c2e4b6a-1d3f-4a5b-8c7d-2e1f0a9b8c7d",
  "url": "https://example.com/snapbar",
  "source": "custom",
  "event_types": ["submission.completed"],
  "experience_ids": ["2f5c1a8e-7d3b-4e1f-9a6c-0b8d4e2f1a37"],
  "consent_policy": "marketing_consented",
  "status": "active",
  "created_at": "2026-07-18T19:20:11.512+00:00",
  "signing_secret": "whsec_…",
  "warning": "Store this signing secret securely. Snapbar will not return it again."
}

Each delivery is a POST with Content-Type: application/json, User-Agent: Snapbar-Integrations/1, X-Snapbar-Event-Id, Idempotency-Key, and X-Snapbar-Signature in the form t=<unix seconds>,v1=<hex HMAC>. The header may carry more than one v1 entry; accept the delivery when any of them matches.

Compute HMAC-SHA256 with your signing secret over the timestamp, a period, and the exact raw body bytes. Accept the request when any v1 value matches and the timestamp is within 300 seconds of your clock. Verify before parsing: re-serializing the JSON changes the bytes.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifySnapbarWebhook(rawBody, signatureHeader, secret) {
  if (typeof signatureHeader !== 'string' || signatureHeader.length > 4096) return false;
  const entries = signatureHeader.split(',').map((entry) => entry.trim().split('=', 2));
  const timestamps = entries.filter(([name]) => name === 't');
  if (timestamps.length !== 1) return false;
  const timestamp = timestamps[0][1];
  const signatures = entries.filter(([name]) => name === 'v1').map(([, value]) => value);

  if (!timestamp || !/^\d+$/.test(timestamp) || signatures.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) return false;

  const expected = createHmac('sha256', secret)
    .update(Buffer.from(`${timestamp}.`, 'utf8'))
    .update(rawBody)
    .digest();

  return signatures.some((candidate) => /^[0-9a-f]{64}$/i.test(candidate) && timingSafeEqual(expected, Buffer.from(candidate, 'hex')));
}

Delivery is at least once. Insert the Idempotency-Key into a table with a unique constraint and apply the side effect in the same transaction, or store the key together with a durable job you process afterwards, then return 2xx without repeating the work when the key already exists. Recording the key without committing the work turns a crash into a false success, because the retry is acknowledged and never redelivered. Use X-Snapbar-Event-Id for correlation only; it identifies the delivery, so different endpoints receive different event ids and idempotency keys for the same submission.

Start your receiver with the registered signing secret installed. Replace the endpoint ID below, then run this request with your live key. It sends synthetic data, so your receiver should ignore test: true for business processing.

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer ${SNAPBAR_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"endpoint_id": "YOUR_REGISTERED_ENDPOINT_ID"}' \
  https://integrations.snapbar.com/v1/test/deliveries

With a live manage-webhooks key, call POST /test/deliveries with {"endpoint_id":"..."} after installing that endpoint’s secret in the receiver. Snapbar signs the synthetic payload with the existing secret; no new secret is returned. The response reports endpoint_id, outcome (succeeded or failed), and response_status (an HTTP status or null). The send creates no Activity record, does not expose guest data, and is limited to 10 per key per minute.

{
  "outcome": "succeeded",
  "response_status": 200,
  "endpoint_id": "9c2e4b6a-1d3f-4a5b-8c7d-2e1f0a9b8c7d"
}

Complete one real guest-flow rehearsal with the selected consent policy and event. Confirm the expected result in your app and a Delivered row in Integrations > Activity. Synthetic tests do not appear in Activity. For a moderated display, also verify that pending and rejected photos stay off the screen.

A secret cannot be rotated in place. Register a second endpoint (B) at a new path on the same host with the same event_types, consent_policy, and experience_ids as the current one (A), and store its signing_secret.

Deploy the receiver with both secrets and confirm B using a live manage-webhooks key with POST /test/deliveries and B’s endpoint_id, then with one real rehearsal event. Keep verification enabled. Both A and B may receive the same real event during overlap: dedupe transport retries by Idempotency-Key and make the business operation idempotent by submission.id plus event.type. Delete A only after B passes; removal does not transfer A’s queued work.

Delete A with DELETE /webhook-endpoints/{id}. Queued work closes as Skipped with reason, but a request already sent can still arrive and cannot be recalled. Keep accepting and deduplicating in-flight requests during the cutover; retire the old path and secret after outstanding requests have settled.