DOCS

Beta

/

5 minute read

August 5, 2019

About Webhooks

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.

Note
For the Webhooks API reference, see Webhooks Management.

Using webhooks

When a webhook-enabled event occurs, the Marqeta platform sends 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.

Webhooks are primarily used:

  • For record maintenance, as the source of truth for transactional money movement

  • To understand when an event occurred (for example, when a card holder has passed KYC verification, a user transition notification is sent)

It is strongly recommended (and even expected) that you implement webhooks, as they are crucial to maintaining an internal ledger. Without webhooks, your records will be based on responses to /GET requests to the /webhooks endpoint, or on historical reports accessed through the Program Dashboard. Unlike webhooks, neither are a sufficient source of truth.

Runtime characteristics

The Marqeta platform webhook system handles notification messages by:

  • Retrying failed notification messages.

  • Batching multiple notifications of the same event type in a single message.

  • Including a Basic Auth (base64-encoded) header in the notification message.

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 20 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.

Idempotency

Your webhook endpoint might occasionally receive the same notification more than once. You can handle these rare cases by making your event processing idempotent so duplicate notifications do not have any additional effects.

Tutorial

This tutorial walks you through how to configure your webhook endpoint to subscribe to events.

Step One: Configure your webhook endpoint

Before sending a POST request to the /webhooks endpoint, define the config object, which contains the configuration information for the webhook:

  • Set the url field to the value of the URL of your webhook endpoint, the location to where event notifications are sent.

  • Set the basic_auth_username and basic_auth_password fields to the value of the username and password for accessing your webhook endpoint, respectively.

The following code block shows a sample config object as it would appear in a /POST webhooks request:

"config": {
   "url": "https://my_secure_domain.com/webhook",
   "secret": "My_20-to-50-character_secret",
   "basic_auth_username": "My_50-character-min_username",
   "basic_auth_password": "My_20-to-50-character_password"
 },

Is this helpful?

Step Two: Subscribe to events

Next, before sending a POST request to the /webhooks endpoint, specify the events array, which contains a comma-delimited array of strings (a single string embedded in this field is considered an array of one). Each string can specify one of the following:

  • A single event type, considered an array of one (for example, "transaction.gpa.debit").

  • A group of event types, denoted by an asterisk after the base event type (for example, "transaction.*" or "cardtransition.*").

  • All event types, denoted by a single asterisk in the place of the event type ("*").

It is strongly recommended that you subscribe to all event types initially. For a list of event types the Marqeta platform supports, see Event Types.

The following code block shows a sample subscription to both a single event type and group of event types as it would appear in a /POST webhooks request. The single event type cardtransition.fulfillment.issued represents when a card is issued; the group of event types transaction.* represents any transaction event that occurs:

 "events": [
   "cardtransition.fulfillment.issued,transaction.*"
 ],

Is this helpful?

The following code block shows a sample subscription to all event types as it would appear in a /POST webhooks request:

 "events": [
   "*"
 ],

Is this helpful?

Step Three: Create a webhook

Now that you’ve configured your webhook endpoint to subscribe to events, you can create a webhook.

Send a /POST request to the /webhooks endpoint.

{
 "name": "My_Webhook_Name",
 "active": true,
 "config": {
   "url": "https://my_secure_domain.com/webhook",
   "secret": "My_20-character-min_secret",
   "basic_auth_username": "my_username",
   "basic_auth_password": "My_20-character-min_password"
 },
 "events": [
   "*"
 ],
 "token": "my_webhook_token",
 "created_time": "2016-08-24T23:20:28Z",
 "last_modified_time": "2016-08-24T23:20:28Z"
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.