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.
Setting one up
Section titled “Setting one up”- Give your Golden Arcus contact an https address on a public host name, for example
https://erp.example.com/ga/webhooks. - We give you that address’s signing secret. It starts with
whsec_. - From then on, each event for your account is sent there.
What we send
Section titled “What we send”POST /ga/webhooks HTTP/1.1Host: erp.example.comContent-Type: application/jsonUser-Agent: GoldenArcus-Webhooks/1webhook-id: evt_e3-01JCX7M4Z9Q8R6T5V3W2Y1N0ABwebhook-timestamp: 1794521112webhook-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.
Your answer
Section titled “Your answer”- 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.
Retries
Section titled “Retries”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.
Checking the signature
Section titled “Checking the signature”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)) ); });}import base64import hashlibimport hmacimport time
def verify(secret: str, headers: dict, raw_body: bytes) -> bool: msg_id = headers["webhook-id"] timestamp = headers["webhook-timestamp"] if abs(time.time() - int(timestamp)) > 300: return False
key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + raw_body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
return any( hmac.compare_digest(part.split(",", 1)[1], expected) for part in headers["webhook-signature"].split(" ") if part.startswith("v1,") )function verify(string $secret, array $headers, string $rawBody): bool{ $id = $headers['webhook-id']; $timestamp = $headers['webhook-timestamp']; if (abs(time() - (int) $timestamp) > 300) { return false; }
$key = base64_decode(substr($secret, strlen('whsec_'))); $expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$rawBody", $key, true));
foreach (explode(' ', $headers['webhook-signature']) as $part) { [$version, $signature] = array_pad(explode(',', $part, 2), 2, ''); if ($version === 'v1' && hash_equals($expected, $signature)) { return true; } } return false;}import java.nio.charset.StandardCharsets;import java.security.MessageDigest;import java.util.Base64;import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;
static boolean verify(String secret, String id, String timestamp, String signatureHeader, String rawBody) throws Exception { if (Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(timestamp)) > 300) return false;
byte[] key = Base64.getDecoder().decode(secret.substring("whsec_".length())); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(key, "HmacSHA256")); byte[] signed = (id + "." + timestamp + "." + rawBody).getBytes(StandardCharsets.UTF_8); String expected = Base64.getEncoder().encodeToString(mac.doFinal(signed));
for (String part : signatureHeader.split(" ")) { if (part.startsWith("v1,") && MessageDigest.isEqual( part.substring(3).getBytes(StandardCharsets.UTF_8), expected.getBytes(StandardCharsets.UTF_8))) { return true; } } return false;}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.
Where we call from
Section titled “Where we call from”Our deliveries come from one fixed address. If your firewall allows callers by address, ask us for it.