Webhooks
Webhooks are notifications about API events, sent as they occur. The Marqeta platform sends these notifications to an endpoint that is hosted in your environment and configured to receive and process them.
Create a webhook object to represent your webhook endpoint. Configure it with the URL of your webhook endpoint and a set of credentials for accessing that endpoint. You can configure it to send notifications for a single event, a group of events by type, or all event types. To set up multiple webhook endpoints and route different types of event notifications to each, create multiple webhook objects and configure each to send a specific type of event notification to a specific endpoint.
See About Webhooks for information on notifications and a tutorial that walks you through the configuration of your webhook endpoint.
See Event Types for reference documentation on the types of events that the Marqeta platform supports.
Note
Webhooks URLs are cached. Changes made on your webhook endpoint can take up to one hour to be applied.
Create webhook
Copy section link
Action: POST
Endpoint: /webhooks
Creates a webhook.
Request body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the webhook is active. Allowable Values:
Default value: |
config
object
|
Contains the configuration information for the webhook. Allowable Values: Valid |
config.basic_auth_password
string
|
Password for accessing your webhook endpoint. Allowable Values: 20–50 chars
|
config.basic_auth_username
string
|
Username for accessing your webhook endpoint. Allowable Values: 1–50 chars |
config.custom_header
object
|
Custom headers to be passed along with the request. Allowable Values: Up to three name-value pairs: 500 char max per name, 500 char max per value |
config.secret
string
|
A randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars
|
config.url
string
|
URL of your webhook endpoint. Allowable Values: 1–255 chars
|
config.use_mtls
boolean
|
Set to Allowable Values:
|
events
array of strings
|
Specifies the types of events for which notifications are sent. The wildcard character NOTE: You can only use the wildcard character with the base type events, not subcategories.
For example, you cannot subscribe to Allowable Values: For a comprehensive list of events, see Event Types. |
name
string
|
Descriptive name of the webhook. Allowable Values: 1–64 chars |
token
string
|
Unique identifier of the webhook. Allowable Values: 1–36 chars |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the webhook is active. This field is returned if you included it in your webhook. Allowable Values:
|
config
object
|
Contains the configuration information for the webhook. Allowable Values: Valid |
config.basic_auth_password
string
|
Password for accessing your webhook endpoint. Allowable Values: 20–50 chars
|
config.basic_auth_username
string
|
Username for accessing your webhook endpoint. Allowable Values: 1–50 chars |
config.custom_header
object
|
Custom headers to be passed along with the request. Allowable Values: Up to three name-value pairs: 500 char max per name, 500 char max per value |
config.secret
string
|
A randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars
|
config.url
string
|
URL of your webhook endpoint. Allowable Values: 1–255 chars
|
config.use_mtls
boolean
|
Set to Allowable Values:
|
created_time
datetime
|
Date and time when the webhook event was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
events
array of strings
|
Specifies the types of events for which notifications are sent. The wildcard character NOTE: You can only use the wildcard character with the base type events, not subcategories.
For example, you cannot subscribe to Allowable Values: For a comprehensive list of events, see Event Types. |
last_modified_time
datetime
|
Date and time when the associated object was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
name
string
|
Descriptive name of the webhook. Allowable Values: 1–64 chars |
token
string
|
The unique identifier of the webhook. Allowable Values: 1–36 chars |
List webhooks
Copy section link
Action: GET
Endpoint: /webhooks
Returns an array of all webhooks.
This endpoint supports field filtering, sorting, and pagination.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Set to Allowable Values:
|
count
integer
|
The number of resources to retrieve. Allowable Values: 1-10 |
start_index
integer
|
The sort order index of the first resource in the returned array. Allowable Values: Any integer |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
The number of resources to retrieve. Allowable Values: 1-10 |
data
array of objects
|
An array of webhooks objects. Allowable Values: One or more webhook objects |
data[].active
boolean
|
Indicates whether the webhook is active. This field is returned if you included it in your webhook. Allowable Values:
|
data[].config
object
|
Contains the configuration information for the webhook. Allowable Values: Valid |
data[].config.basic_auth_password
string
|
Password for accessing your webhook endpoint. Allowable Values: 20–50 chars
|
data[].config.basic_auth_username
string
|
Username for accessing your webhook endpoint. Allowable Values: 1–50 chars |
data[].config.custom_header
object
|
Custom headers to be passed along with the request. Allowable Values: Up to three name-value pairs: 500 char max per name, 500 char max per value |
data[].config.secret
string
|
A randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars
|
data[].config.url
string
|
URL of your webhook endpoint. Allowable Values: 1–255 chars
|
data[].config.use_mtls
boolean
|
Set to Allowable Values:
|
data[].created_time
datetime
|
Date and time when the webhook event was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].events
array of strings
|
Specifies the types of events for which notifications are sent. The wildcard character NOTE: You can only use the wildcard character with the base type events, not subcategories.
For example, you cannot subscribe to Allowable Values: For a comprehensive list of events, see Event Types. |
data[].last_modified_time
datetime
|
Date and time when the associated object was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].name
string
|
Descriptive name of the webhook. Allowable Values: 1–64 chars |
data[].token
string
|
The unique identifier of the webhook. Allowable Values: 1–36 chars |
end_index
integer
|
The sort order index of the last resource in the returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of Allowable Values: Any integer |
start_index
integer
|
The sort order index of the first resource in the returned array. Allowable Values: Any integer |
Update webhook custom headers
Copy section link
Action: PUT
Endpoint: /webhooks/customheaders/{token}
Adds or updates a webhook’s custom HTTP headers.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the webhook. Allowable Values: Existing webhook token |
Request body
Copy section link
| Fields | Description |
|---|---|
custom_header
object
|
Additional custom information included in the HTTP header. For example, this might contain security information, along with Basic Authentication, when making a JIT Funding request. Allowable Values: Up to three name-value pairs: 500 char max per name, 500 char max per value |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the webhook is active. This field is returned if you included it in your webhook. Allowable Values:
|
config
object
|
Contains the configuration information for the webhook. Allowable Values: Valid |
config.basic_auth_password
string
|
Password for accessing your webhook endpoint. Allowable Values: 20–50 chars
|
config.basic_auth_username
string
|
Username for accessing your webhook endpoint. Allowable Values: 1–50 chars |
config.custom_header
object
|
Custom headers to be passed along with the request. Allowable Values: Up to three name-value pairs: 500 char max per name, 500 char max per value |
config.secret
string
|
A randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars
|
config.url
string
|
URL of your webhook endpoint. Allowable Values: 1–255 chars
|
config.use_mtls
boolean
|
Set to Allowable Values:
|
created_time
datetime
|
Date and time when the webhook event was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
events
array of strings
|
Specifies the types of events for which notifications are sent. The wildcard character NOTE: You can only use the wildcard character with the base type events, not subcategories.
For example, you cannot subscribe to Allowable Values: For a comprehensive list of events, see Event Types. |
last_modified_time
datetime
|
Date and time when the associated object was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
name
string
|
Descriptive name of the webhook. Allowable Values: 1–64 chars |
token
string
|
The unique identifier of the webhook. Allowable Values: 1–36 chars |
Retrieve webhook
Copy section link
Action: GET
Endpoint: /webhooks/{token}
Retrieves a webhook.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the webhook. Allowable Values: Existing webhook token |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the webhook is active. This field is returned if you included it in your webhook. Allowable Values:
|
config
object
|
Contains the configuration information for the webhook. Allowable Values: Valid |
config.basic_auth_password
string
|
Password for accessing your webhook endpoint. Allowable Values: 20–50 chars
|
config.basic_auth_username
string
|
Username for accessing your webhook endpoint. Allowable Values: 1–50 chars |
config.custom_header
object
|
Custom headers to be passed along with the request. Allowable Values: Up to three name-value pairs: 500 char max per name, 500 char max per value |
config.secret
string
|
A randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars
|
config.url
string
|
URL of your webhook endpoint. Allowable Values: 1–255 chars
|
config.use_mtls
boolean
|
Set to Allowable Values:
|
created_time
datetime
|
Date and time when the webhook event was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
events
array of strings
|
Specifies the types of events for which notifications are sent. The wildcard character NOTE: You can only use the wildcard character with the base type events, not subcategories.
For example, you cannot subscribe to Allowable Values: For a comprehensive list of events, see Event Types. |
last_modified_time
datetime
|
Date and time when the associated object was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
name
string
|
Descriptive name of the webhook. Allowable Values: 1–64 chars |
token
string
|
The unique identifier of the webhook. Allowable Values: 1–36 chars |
Update webhook
Copy section link
Action: PUT
Endpoint: /webhooks/{token}
Updates a webhook.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the webhook. Allowable Values: Existing webhook token |
Request body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the webhook is active. Allowable Values:
Default value: |
config
object
|
Contains the configuration information for the webhook. Allowable Values: Valid |
config.basic_auth_password
string
|
Password for accessing your webhook endpoint. Allowable Values: 20–50 chars
|
config.basic_auth_username
string
|
Username for accessing your webhook endpoint. Allowable Values: 1–50 chars |
config.custom_header
object
|
Custom headers to be passed along with the request. Allowable Values: Up to three name-value pairs: 500 char max per name, 500 char max per value |
config.secret
string
|
A randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars
|
config.url
string
|
URL of your webhook endpoint. Allowable Values: 1–255 chars
|
config.use_mtls
boolean
|
Set to Allowable Values:
|
events
array of strings
|
Specifies the types of events for which notifications are sent. The wildcard character NOTE: You can only use the wildcard character with the base type events, not subcategories.
For example, you cannot subscribe to Allowable Values: For a comprehensive list of events, see Event Types. |
name
string
|
Descriptive name of the webhook. Allowable Values: 1–64 chars |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates whether the webhook is active. This field is returned if you included it in your webhook. Allowable Values:
|
config
object
|
Contains the configuration information for the webhook. Allowable Values: Valid |
config.basic_auth_password
string
|
Password for accessing your webhook endpoint. Allowable Values: 20–50 chars
|
config.basic_auth_username
string
|
Username for accessing your webhook endpoint. Allowable Values: 1–50 chars |
config.custom_header
object
|
Custom headers to be passed along with the request. Allowable Values: Up to three name-value pairs: 500 char max per name, 500 char max per value |
config.secret
string
|
A randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars
|
config.url
string
|
URL of your webhook endpoint. Allowable Values: 1–255 chars
|
config.use_mtls
boolean
|
Set to Allowable Values:
|
created_time
datetime
|
Date and time when the webhook event was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
events
array of strings
|
Specifies the types of events for which notifications are sent. The wildcard character NOTE: You can only use the wildcard character with the base type events, not subcategories.
For example, you cannot subscribe to Allowable Values: For a comprehensive list of events, see Event Types. |
last_modified_time
datetime
|
Date and time when the associated object was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
name
string
|
Descriptive name of the webhook. Allowable Values: 1–64 chars |
token
string
|
The unique identifier of the webhook. Allowable Values: 1–36 chars |
Ping webhook
Copy section link
Action: POST
Endpoint: /webhooks/{token}/ping
Pings webhook endpoint.
Send a ping request to your webhook endpoint to validate credentials and connectivity. Your webhook endpoint must be configured to respond.
Configuring your webhook endpoint
This subsection describes the ping request that your webhook endpoint should expect and its expected response.
When the Marqeta platform receives the ping request, it sends a POST request containing the following body to the URL of your webhook endpoint:
To indicate that it is functioning properly, your webhook endpoint must respond with a status code of "200" (see Signature Verification for a code example that identifies a ping request). The response can optionally include a JSON-formatted body, for example:
The Marqeta platform then responds to its requestor by echoing, as-is, the response code and body received from your webhook endpoint.
Using the ping facility
To ping a webhook endpoint, send a POST request to /webhooks/{token}/ping and use the token path parameter to specify the webhook to ping.
Include an empty, JSON-formatted body in the request, that is:
The following chain of actions occurs during a successful ping:
-
The Marqeta platform receives the ping request (
POSTto/webhooks/{token}/ping). -
The Marqeta platform sends a request to your webhook endpoint.
-
Your webhook endpoint responds with a status code of "200" and an optional body.
-
The Marqeta platform responds to its requestor by echoing, as-is, the response code and body received from your webhook endpoint.
Note
If the customer-hosted endpoint fails to respond within five seconds, the Marqeta platform times out the request and responds with the following message body (where<optional message> represents additional details you can choose to include in the response):
Failed pings are not automatically retried.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the webhook. Allowable Values: Existing webhook token |
Response body
Copy section link
| Fields | Description |
|---|---|
pings
array of objects
|
An array of ping requests to your webhook endpoint. Allowable Values: One or more |
pings[].payload
string
|
The payload of the ping request. Allowable Values: 255 char max |
pings[].token
string
|
The unique identifier of the ping request. Allowable Values: 255 char max |
Resend event notification
Copy section link
Action: POST
Endpoint: /webhooks/{token}/{event_type}/{event_token}
Resends an event notification to your webhook endpoint.
Although you send this request as a POST, all parameters are passed in the URL and the body is empty.
The event notification is resent to your webhook endpoint and also returned in the response to this request.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the webhook. Allowable Values: Existing webhook token |
event_type
string
|
Specifies the type of event you want to resend. Allowable Values:
|
event_token
string
|
The token identifying the event for which you want to resend a notification. Allowable Values: Existing event token |