Webhooks

We tell your server when something happens, by HTTP POST. Every delivery is signed, carries a timestamp and an event id, and is retried until you acknowledge it.

Delivery status

Each account will have one webhook endpoint, and a signing secret for it. Treat that secret exactly like an API key: in a secret store, never in source code.

How a delivery is signed

Each delivery carries three headers:

The signed material is the timestamp, a full stop, and the request body exactly as sent:

{timestamp}.{raw request body}

Because the timestamp is inside the signature, it cannot be changed to slip an old delivery past your replay check — and because the body is too, the signature is valid for exactly one body.

Verify a delivery

1. Read the raw body before anything parses it. Parsing JSON and serialising it again changes the bytes — spacing, key order, escaping — and the signature will no longer match. Most frameworks parse by default; switch that off for this one route.
2. Check the timestamp is within 300 seconds of your clock, in either direction. Reject it otherwise. Keep your servers' clocks synchronised.
3. Compute the HMAC over {timestamp}.{raw body} with your signing secret, and hex-encode it.
4. Compare in constant time. An ordinary string comparison stops at the first difference, and the time it takes leaks how much of a forged signature was right.
5. Only then parse the body and act on it.

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

const REPLAY_WINDOW_SECONDS = 300

/**
 * True only for a delivery we signed, sent within the replay window.
 * rawBody must be the request body exactly as received — a Buffer or string,
 * never JSON you have parsed and re-serialised.
 */
export function verifyVertexBridgeWebhook({ secret, rawBody, timestampHeader, signatureHeader, now = Date.now() }) {
  if (typeof timestampHeader !== 'string' || typeof signatureHeader !== 'string') return false
  if (!/^[0-9]+$/.test(timestampHeader)) return false
  const timestamp = Number(timestampHeader)
  if (Math.abs(Math.floor(now / 1000) - timestamp) > REPLAY_WINDOW_SECONDS) return false

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader)
  return a.length === b.length && timingSafeEqual(a, b)
}

import express from 'express'

const app = express()

// express.raw, not express.json: the signature covers the bytes we sent.
app.post('/webhooks/vertexbridge', express.raw({ type: '*/*' }), (req, res) => {
  const ok = verifyVertexBridgeWebhook({
    secret: process.env.VERTEXBRIDGE_WEBHOOK_SECRET,
    rawBody: req.body,
    timestampHeader: req.get('X-VertexBridge-Timestamp'),
    signatureHeader: req.get('X-VertexBridge-Signature'),
  })
  if (!ok) return res.sendStatus(400)

  const eventId = req.get('X-VertexBridge-Event-Id')
  // Record eventId; if you have seen it before, stop here and still answer 200.
  queueForProcessing(eventId, req.body)
  res.sendStatus(200)
})

A delivery that fails verification gets a 400 and nothing else. Do not log the body of a delivery you could not verify; you cannot know who wrote it.

Test your verifier

These values were produced by our signing code. A correct verifier accepts them when its clock reads the timestamp — pass now explicitly — and rejects them if any single byte changes.

Duplicates and order

Delivery is at least once. If your server took the event but its answer never reached us, we send it again with the same X-VertexBridge-Event-Id. Store the event ids you have processed, and when one repeats, answer 200 and do nothing else.

Delivery is not ordered. A retry can arrive after a later event's first attempt. Never assume the newest delivery describes the newest state; when order matters, read the current state from the API.

Responding

Any 2xx status means delivered, and we stop. Anything else — another status, a refused connection, no answer — counts as a failed attempt and is retried.

Answer as soon as the delivery is verified and recorded, and do the work afterwards. An endpoint that does its processing before it answers turns every slow day into a wave of retries.

Retries

A delivery is attempted up to 10 times, each attempt waiting longer than the last, so that an endpoint that is down for a deploy recovers without losing anything:

If attempt 10 fails too — about 21 hours 53 minutes after the first — we stop, and the delivery is marked abandoned. It stays in your delivery log, and you can send it again.

The delivery log

Every delivery queued for you, newest first. Needs the read scope; limit defaults to 50 and is capped at 200.

curl "$VERTEXBRIDGE_API_BASE/v1/partner/deliveries?limit=20" \
  -H "X-API-Key: $VERTEXBRIDGE_API_KEY"

[]

Until we send webhooks the log is empty. Each delivery in it is an object with these fields:

The log holds the count of attempts and the last answer, not a history of each attempt.

Replaying a delivery

Once a delivery is abandoned, you can have it sent again — after fixing your endpoint, for example. It goes back to pending and starts the retry schedule from attempt 1, with the same event id, so your deduplication still recognises it.

curl -X POST "$VERTEXBRIDGE_API_BASE/v1/partner/deliveries/6f1d2c3b-8a4e-4f5d-9b6a-0c1e2d3f4a5b/replay" \
  -H "X-API-Key: $VERTEXBRIDGE_API_KEY"

{ "delivery_id": "6f1d2c3b-8a4e-4f5d-9b6a-0c1e2d3f4a5b", "status": "pending" }

Only an abandoned (or failed) delivery can be replayed. A delivery that is still pending is already being retried, and one that was delivered reached you; both answer 404 not_found, as does an id that is not yours — the same answer, so the endpoint cannot be used to discover which ids exist.

The recipe, from the API

GET /v1/partner/webhook-signing returns the header names and replay window from the same constants our signer uses. Read it in a test of your own if you want to know the moment anything changes.

{
  "algorithm": "HMAC-SHA256",
  "signed_material": "{timestamp}.{raw_request_body}",
  "signature_header": "X-VertexBridge-Signature",
  "timestamp_header": "X-VertexBridge-Timestamp",
  "event_id_header": "X-VertexBridge-Event-Id",
  "replay_window_seconds": 300,
  "notes": [
    "Compare signatures in constant time.",
    "Reject a delivery whose timestamp is outside the replay window.",
    "Deduplicate on the event id header — we retry, so you will see the same event more than once.",
    "Verify against the RAW body bytes; re-serialising JSON changes them."
  ]
}

Next: Errors.