Webhooks

Verifying the events Superroute sends about deposits and pickups.

Events

The carrier_package.distribution.* events of the carrier channel are verified the same way.

Verification

Verify every webhook against the raw body exactly as received, before parsing it. sLocker checks the timestamp (5 minutes either way by default), the X-Webhook-Content-Digest header and the X-Webhook-Signature header, and returns the event.

• The signature is v1= followed by the base64 HMAC-SHA256 of {timestamp}\n{X-Webhook-Delivery-Id}\n{body}, made with the signing secret of your endpoint.
• During a key rotation the previous secret stays valid for 24 hours: pass both secrets.
• Endpoints switched to Standard Webhooks headers or to CloudEvents bodies are verified as well.
• Handle each eventId once: it stays the same on every retry, while deliveryId changes on every attempt.
• Answer with a 2xx status within 10 seconds, and keep sandbox events (event.test) apart from production.

// JavaScript / TypeScript (Express)
import { verifyWebhook, WebhookVerificationError } from '@superrouteca/slocker';

app.post('/webhooks/slocker', express.raw({ type: '*/*' }), async (req, res) => {
  try {
    const event = await verifyWebhook(req.body, req.headers, [process.env.SLOCKER_SECRET, process.env.SLOCKER_OLD_SECRET]);
    if (!event.test) await queue.add(event.eventId, event);
    res.sendStatus(204);
  } catch (e) {
    if (e instanceof WebhookVerificationError) return res.status(400).send(e.reason);
    throw e;
  }
});

Each language

# Python
import slocker

event = slocker.verify(request.get_data(), dict(request.headers), [secret, old_secret])

// PHP
use Superroute\SLocker\Webhooks;

$event = Webhooks::verify(file_get_contents('php://input'), getallheaders(), [$secret, $oldSecret]);

// Go
event, err := slocker.Verify(body, slocker.HeaderMap(r.Header), []string{secret, oldSecret}, nil)

// C# / .NET
var webhookEvent = Webhooks.Verify(body, headers, new[] { secret, oldSecret });

A refused webhook raises an error with one of these reasons:

• MISSING_HEADER
• INVALID_TIMESTAMP
• TIMESTAMP_OUT_OF_TOLERANCE
• DIGEST_MISMATCH
• SIGNATURE_MISMATCH
• INVALID_PAYLOAD