> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# About Webhooks
> Learn how the Marqeta platform's webhook system handles event notifications, the run-time characteristics of the webhook system, and how to configure your webhook endpoint to capture API events as they occur.
Use webhooks to receive information about API events as they occur. 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. For example, when a card is used, a webhook is sent with details of the attempted transaction. To receive and process webhook-enabled events, configure a webhook endpoint in your environment.
See [Webhooks](/core-api/webhooks/) for the complete endpoint reference.
See [Event Types](/core-api/event-types/) for reference documentation on the types of events that the Marqeta platform supports.
Using webhooks
When a webhook-enabled event occurs, the Marqeta platform sends an HTTPS `POST` request containing information about the event to a preconfigured 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 cardholder has passed [KYC verification](/core-api/kyc-verification/), a [user transition notification](/core-api/event-types/#_account_holder_transition_events) is sent).
Marqeta strongly recommends that you implement webhooks.
**Note**\
Each program can have up to five active webhooks.
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.
Below are the run-time characteristics of the Marqeta platform’s 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` endpoint messaging failure, the message is not resent. |
| Retry interval | An exponential backoff increases the interval between retries by powers of four after each subsequent messaging failure. In other words, the retry interval follows this pattern: 4 seconds, 16 seconds, 64 seconds, and so on, up to an interval just over 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 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 that is necessary for your business logic.
Idempotency
Your webhook endpoint might occasionally receive the same notification more than once, such as in the case of a messaging failure. You can handle these rare cases by making your event processing [idempotent](/core-api/idempotency/) so duplicate notifications do not have any additional effects. To support idempotency, each transaction is identified by a unique transaction token, and each webhook is identified by a unique event token.
Stand-in Processing webhooks
Stand-in Processing (STIP) occurs when one party in the authorization flow is unable to complete processing within the time allocated or when specific transactional rules are set up at the card network level. In such cases, card issuers can let the card network approve transactions on their behalf. The card network will make authorization decisions as necessary and subsequently notify the Marqeta platform with information about the transactions that occurred while STIP was enabled.
STIP can occur in either of the following two scenarios:
* Authorizations that the Marqeta platform did not receive
* Authorizations that the Marqeta platform received and processed
When a transaction is processed using STIP, the Marqeta platform sends an informative event webhook that has no impact on the cardholder balance. As shown in the example below, why the transaction was approved or declined is provided in the webhook’s `standin_reason` field. This information enables you to better understand the reason behind the decision and the impact on your cardholders.
```json JSON lines wrap theme={null}
{
"transactions": [
{
"type": "authorization",
"state": "DECLINED",
"identifier": "12544010",
"token": "TRANSACTION A",
"amount": 3.50,
"response": {
"code": "1844",
"memo": "Network decline advice"
}
"standin_by": "NETWORK",
"standin_reason": "acquirer_issue"
}
]
}
```
Common STIP reason codes
Below is a list of the STIP reason codes per card network that you might encounter, the most common of which are `issuer_timeout`, `issuer_unavailable`, `acquirer_issue`, and `suspected_fraud_transaction`.
| Reason Code | Visa | Mastercard | Pulse |
| ------------------------------------ | ---- | ---------- | ----- |
| `issuer_timeout` | ✓ | ✓ | ✓ |
| `issuer_unavailable` | ✓ | ✓ | ✓ |
| `token_provisioning_service` | ✓ | ✓ | ✓ |
| `acquirer_issue` | ✓ | | ✓ |
| `pin_error` | ✓ | ✓ | |
| `issuer_logged_off` | | ✓ | ✓ |
| `forced_stip_by_issuer` | ✓ | | ✓ |
| `suspected_fraud_transaction` | ✓ | | |
| `visa_payment_controls_rule` | ✓ | | |
| `selective_acceptance_service` | ✓ | | |
| `additional_authentication_required` | ✓ | | |
| `recurring_payment` | ✓ | | |
Tutorial
This tutorial walks you through how to configure your webhook endpoint to subscribe to events.
**Tip**\
Webhook configurations created by the `/webhooks` endpoint are functional in both the production and public/private sandbox environments. If you want to test webhooks in your sandbox environment, configure a webhook object within the simulated transaction. For more information, see the Simulations 2.0 API for [card transactions](/core-api/simulations-card-transactions/) and [direct deposits](/core-api/simulations-direct-deposits/).
**Note**\
Webhooks URLs are cached. Changes made on your webhook endpoint can take up to one hour to be applied.
Define the `config` object in the request body, which contains 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` request:
```json JSON lines wrap theme={null}
"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"
},
```
Step 2 — Subscribe to event notifications
Specify the `events` array in the request body, which contains a comma-delimited array of strings (a single string embedded in this field is considered an array of one). Each string represents:
* A single event type (for example, `transaction.gpa.debit`).
* A group of event types, denoted by an asterisk after the base event type (for example, `transaction.*` or `cardtransition.*`). You can only use the wildcard character with the *base* type events, not subcategories. For example, you cannot subscribe to `cardtransition.fulfillment.*` events, but you can subscribe to `cardtransition.*`.
* All event types, denoted by a single asterisk in the place of the event type (for example, `*`).
Marqeta strongly recommends that you subscribe to all event types initially. For a list of event types the Marqeta platform supports, see [Event Types](/core-api/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` 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:
```json JSON lines wrap theme={null}
"events": [
"cardtransition.fulfillment.issued",
"transaction.*"
],
```
The following code block shows a sample subscription to all event types as it would appear in a `POST` request:
```json JSON lines wrap theme={null}
"events": [
"*"
],
```
Step 3 — Create a webhook
Now that your webhook endpoint has been configured to subscribe to event notifications in the request body, you can create a webhook.
Send a `POST` request to the `/webhooks` endpoint. The following code block shows a sample request:
```json JSON lines wrap theme={null}
{
"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-to-50-character_password"
},
"events": [
"*"
],
"token": "my_webhook_token",
"created_time": "2024-08-24T23:20:28Z",
"last_modified_time": "2024-08-24T23:20:28Z"
}
```