Webhooks Overview

The Marqeta platform can push webhook-style notifications to your system in response to a variety of events. An event is an activity that happens outside of your system, such as a card transaction at a point-of-sale (POS) terminal or a card activation. Notifications contain useful information pertinent to the events. For example, a notification might alert you that a card was used and include details regarding the outcome of the attempted transaction.

Using webhooks

When a webhook-enabled event occurs, the Marqeta platform issues an HTTPS POST containing information about the event to a pre-configured endpoint hosted on your system. You must have an environment configured to listen for and process event notifications in order to take advantage of this functionality. For information about configuring the Marqeta platform to send event notifications to your webhook endpoint, see Webhooks Management.

The Marqeta platform pushes notifications for the following events:

  • Account Holder Transition Events include activities that cause the transition of a user's or business's status field.
  • Card Transition Events include activities such as a card being activated/deactivated, ordered, or shipped. From a technical point of view, they are activities that cause the transition of a card's state or fulfillment_status field.
  • Digital Wallet Token Transition Events include activities such as a digital wallet token being requested, activated, terminated, etc. From a technical point of view, they are activities that cause the transition of a token's state or fulfillment_status field.
  • Chargeback Transition Events mark the progress of disputes through the arbitration process. From a technical point of view, these events cause the transition of a chargeback object's state field.
  • Transaction Events include activities such as authorizations, authorization clearings, and refunds. Note: Although you might think of an authorization and authorization clearing as two parts of the same conceptual transaction, the Marqeta platform treats each transaction-related message exchange as a separate transaction event with a unique identifying token.

See Event Types for sample notification messages.

Runtime characteristics

These are the run-time characteristics of the Marqeta platform webhook system.

Name                                  Description
Number of Retry Attempts In case of a messaging failure, the Marqeta platform attempts to resend a notification message 10 times. A messaging failure is defined as any HTTP response code other than 200.

Note: In the case of a Ping message failure, the message is not resent.
Retry Interval An exponential backoff increases the interval between retries by powers of 4 after each subsequent messaging failure. In other words, the retry interval follows this pattern: 41 (4) secs, 42 (16) secs, 43 (64) secs ... 410 secs (a little more than 12 days).
Maximum Batch Size The Marqeta platform reduces the number of event notification messages by batching multiple notifications of the same type and sending them together in a single message. A maximum of 10 transaction notifications, 100 card-transition notifications, or 100 digital wallet token transition notifications are sent per message.
Authentication The Marqeta platform includes a Basic Auth (base64 encoded) header in the notification message. Your environment must be configured to perform this type of authentication.

Event notification processing

Your webhook endpoint might receive notifications in a different order from which the underlying events occur. You can use the created_time field to determine the correct chronological order if it is necessary for your business logic.

Your webhook endpoint might occasionally receive the same notification more than once. You can handle these rare cases by making your event processing idempotent.