Signature verification

Why sign anything?

Your ingest URL is unguessable but not secret forever. Signing lets your handler prove that a delivery came from ShellOrbit and was not replayed by someone who captured it.

How do I verify a ShellOrbit delivery?

Every delivery carries a signature header:

ShellOrbit-Signature: t=1788445441,v1=5f2b1c9a0d...

The signed payload is the timestamp, a dot, and the raw body. Compute HMAC SHA256 with your endpoint signing secret and compare in constant time.

import crypto from 'node:crypto';

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(parts.v1 ?? '', 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Verify against the raw body. Parsing to JSON and re-serialising changes bytes and breaks the comparison.

Can you verify the provider’s signature for me?

On Business plans, yes. Store the provider’s signing secret against the endpoint and inbound events are verified on receipt. A failed verification is stored and marked rather than dropped, so you can see attempts that did not check out.

How do I rotate a signing secret?

Create a second secret from the dashboard. Both verify for the overlap window you choose, up to 24 hours, so you can deploy the new one without a gap. Revoke the old one when your handler is verifying with the new.

What is IP allowlisting?

On Business plans you can restrict which source addresses may post to an endpoint. Use it where a provider publishes stable egress ranges. Requests from outside the list are rejected at the edge with 403 and are not stored or counted.