Events and webhooks

Whatever changes in the bank is recorded as an event. Read them from /events, or have them delivered to an endpoint of yours.

Subscribing

Create a webhook endpoint with a url and the event_types it wants: exact types, a prefix such as payments.*, or * for everything. The signing secret is returned once, when the endpoint is created.

Verifying a delivery

Each delivery carries three headers: Corgi-Signature, Corgi-Event-Id and Corgi-Webhook-Endpoint-Id. The signature reads t=<unix seconds>,v1=<hex>, where the hex is the HMAC-SHA256 of <t>.<body> under the endpoint's secret.

Compute the same HMAC over the timestamp, a dot and the raw body, and compare in constant time.
Refuse a timestamp more than five minutes from now, so a captured delivery cannot be replayed.
While a secret is being rotated the header lists two v1 values, the new secret's first. Accept the delivery if either matches.

Retries

A delivery that is not acknowledged is tried again after a minute, then with the wait doubling up to six hours, 25 attempts in all: a little over three days. Every attempt is kept as a webhook delivery, and a failed one can be retried by hand. Deliveries can repeat, so treat Corgi-Event-Id as the idempotency key on your side.