Skip to main content
Most of what matters happens after your request returns: a card finishes provisioning, a funding is confirmed, a cardholder is verified, a purchase is approved. A webhook is how you hear about it: FYATU sends an HTTPS POST to your server for every event you subscribed to. Build on webhooks rather than polling: polling spends your rate limit, and a webhook reaches you as soon as the event happens.

Subscribing

Register an endpoint with the events it should receive:
  • The response carries the endpoint’s signing secret, shown once. Store it now.
  • A live endpoint must use https://, and it cannot point at a private or internal address.
  • Up to 10 endpoints per business. One endpoint may take every event.
  • An endpoint receives the events of its own environment: sandbox events go to sandbox endpoints.
  • GET /event-types returns every event you can subscribe to, and the event list describes each one; every event also has its own page under Webhooks.
Manage endpoints with GET, PATCH and DELETE /webhooks/{id}. Sending a test event, resending a delivery, rotating the secret and reading the delivery history are in the CaaS portal under Developers → Webhooks.

What a delivery looks like

event names the event and data carries its details; each event’s page documents its data.

Verifying the signature

Every delivery is signed with your endpoint’s secret, so you can prove it came from FYATU and was not altered. Verify it on the raw request body, before parsing it, and reject anything that fails:
  1. Read t and v1 from X-Fyatu-Signature.
  2. Derive the signing key: the SHA-256 hex digest of your secret.
  3. Compute HMAC-SHA256 of "{t}.{raw body}" with that key, and compare it with v1 in constant time.
  4. Reject a t more than a few minutes old, so an intercepted delivery cannot be replayed later.
Signature Verification has the code in Node.js, Python, PHP, Go and Ruby.

Answering

  • Answer 2xx within 30 seconds. Anything else counts as a failure.
  • Answer first, then do the work: store the event and process it in the background, so a slow database or a third-party call never makes you miss the deadline.
  • The response body is ignored.

Retries

A delivery your endpoint answers with a non-2xx status is tried 5 times in all: at once, then after 15 seconds, 2 minutes, 15 minutes and 1 hour. A delivery that gets no answer at all — your endpoint refuses the connection, its host name does not resolve, or it does not answer within 30 seconds — is retried on the same schedule. The delivery log in Developers → Webhooks shows why each attempt failed, and anything that ran out of attempts can be resent from there.
An endpoint on a private or internal address (loopback, private ranges, link-local, cloud metadata) is refused when you save it, with 422 WEBHOOK_URL_BLOCKED, and is never delivered to.

Handling an event twice, or out of order

Delivery is at least once. The same event can arrive more than once, for example when we retry after your server processed it but answered late, or when a delivery is resent.
  • Deduplicate on X-Fyatu-Event-ID (the eventId in the body). It is the same on every retry and resend of one event; X-Fyatu-Delivery changes with each attempt.
  • Do not rely on order. A CARD_FUNDED can arrive before the CARD_ISSUED it follows. Treat each event as “this happened”, and read the resource with the API when you need its current state.

Which events to start with

Endpoints