Overview & Delivery Behavior

Webhooks let you react to changes on Penny the moment they happen, instead of polling. Every subscription, verification, and delivery-history lookup lives on Penny Banking — even for events about Issuing objects like cards and cardholders. See Subscribing to Webhooks to set one up.

The envelope

Every delivery is a POST of one JSON object to the URL you registered. Abridged example:

{
  "event_id": "notification_event_0193726c-a65e-76c3-8bfb-a65e6c3bfb2f",
  "business_id": "business_01937b95-484e-75af-8c68-484e5afc68d3",
  "type": "card.issued",
  "category": "object",
  "schema_version": "1.0",
  "event_time": "2026-08-25T14:03:11.123456+00:00",
  "occurrence_time": "2026-08-25T14:03:10.987654+00:00",
  "data": {
    "category": "object",
    "operation": "created",
    "subject": { "object_type": "card", "object_id": "card_019375de-a2a0-7f31-884a-a2a0f3184abd" },
    "object": {
      "card_id": "card_019375de-a2a0-7f31-884a-a2a0f3184abd"
      // … the rest of the card object
    }
  }
}

type tells you which kind of event this is — see the Event Catalog for the full list of object- and alert-category events. data’s shape depends on category:

message events don’t have a fixed set of type identifiers the way object/alert events do — handle them by category rather than expecting them in the Event Catalog.

Delivery behavior

• Timeout — Penny waits 5 seconds for your endpoint to respond. Respond quickly and process asynchronously if the work takes longer than that.
• Retries — a non-2xx response, timeout, or connection error schedules a retry. Penny makes up to 10 retries (11 attempts in total) on the schedule below. Each delay varies by up to ±10% so retries don’t arrive in lockstep. If the final retry also fails, the delivery is marked failed and no further attempts are made.

• Event history — every event Penny has generated for your business is queryable on Penny Banking. GET /notifications/webhooks/events lists events; pass the optional identifier query parameter (an event type such as transaction.created) to return only events of that type. To inspect a single event, call GET /notifications/webhooks/events/{notification_event_id}, which also returns the exact payload that was delivered. These endpoints are listed under Platform › Notifications in the Banking API reference.
• Ordering isn’t guaranteed — use the resource’s own state (for example, a transaction’s stage, from Transactions) rather than assuming events arrive in the order they occurred.

Endpoint lifecycle

A notification endpoint moves through a status field with nine possible values as it’s created, verified, and operated:

See Subscribing to Webhooks for the full registration-to-verification flow, including how to poll for these transitions.

Handling duplicate deliveries

Because a slow or failing response is retried, the same event_id can arrive more than once. Use it as a dedupe key — if you’ve already processed an event with that ID, it’s safe to acknowledge and discard the retry rather than reprocess it.

Verifying who sent it

For inbound requests, check the endpoint’s configured bearer token and HMAC signature before processing the body. The same checks apply to event deliveries and Live Decisioning requests. Signing is optional until you create a signing secret.

Confirming you control the endpoint

A newly created webhook won’t deliver anything until it’s verified — Penny sends a challenge to the URL you registered, and you submit the code back. See Subscribing to Webhooks for the exact calls.

Delivery status

Status belongs to each delivery, not to the event. One event produces one delivery per matching endpoint, and each delivery tracks its own attempts. Use GET /notifications/webhooks/events/{notification_event_id}/deliveries to list an event’s deliveries, or GET /notifications/webhooks/{notification_endpoint_id}/deliveries to list deliveries to one endpoint. Both are paginated and return only deliveries belonging to your business.

Each delivery includes: