Skip to content

Webhooks

With a webhook you do not have to keep asking. When something you can see on a shipment changes, we send the event to an address on your side, usually within a minute.

  1. Give your Golden Arcus contact an https address on a public host name, for example https://erp.example.com/ga/webhooks.
  2. We give you that address’s signing secret. It starts with whsec_.
  3. From then on, each event for your account is sent there.
POST /ga/webhooks HTTP/1.1
Host: erp.example.com
Content-Type: application/json
User-Agent: GoldenArcus-Webhooks/1
webhook-id: evt_e3-01JCX7M4Z9Q8R6T5V3W2Y1N0AB
webhook-timestamp: 1794521112
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{"id":"evt_e3-01JCX7M4Z9Q8R6T5V3W2Y1N0AB","object":"event", ...}

The body is the same event object that GET /v1/events lists, with the whole shipment inside. The headers follow the Standard Webhooks specification, so its libraries work with ours.

  • Answer with any 2xx status within 10 seconds. The body is ignored.
  • Do the slow work after you have answered: save the event, answer, then process it.
  • Any other answer, a redirect, or no answer in time counts as a failure, and we try again.

After a failure we try again after 1 minute, then 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours and 24 hours: nine tries over about three days. If the last one fails we switch the address off and stop sending. Nothing is lost: the same events stay in GET /v1/events for 90 days. Tell us when your side is back and we switch it on again.

  • A retry carries the same webhook-id. If you already have that id, answer 2xx and do nothing more.
  • Deliveries can arrive out of order. Each one holds the whole shipment: keep the one with the newest updated_at.

Check every delivery before you trust it. The signature is an HMAC-SHA256 of

{webhook-id}.{webhook-timestamp}.{the raw body}

keyed with your signing secret (the part after whsec_, decoded from base64), and written as v1, followed by the result in base64. Use the raw body exactly as received, before any JSON parsing. Refuse a delivery whose timestamp is more than five minutes from your own clock.

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret, headers, rawBody) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key)
.update(`${id}.${timestamp}.${rawBody}`)
.digest('base64');
return String(headers['webhook-signature'])
.split(' ')
.some((part) => {
const [version, signature = ''] = part.split(',');
return (
version === 'v1' &&
signature.length === expected.length &&
timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
);
});
}

To test your code, this example is from the Standard Webhooks specification:

Secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
webhook-id msg_p5jXN8AQM9LWM0D4loKWxJek
webhook-timestamp 1614265330
Body {"test": 2432232314}
webhook-signature v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

Skip the five-minute check when you try it: the timestamp is from 2021.

Our deliveries come from one fixed address. If your firewall allows callers by address, ask us for it.