Webhooks Management

25 minute read

October 6, 2021

Webhooks Management

Hidden

Webhooks are notifications about API events, sent as they occur. The Marqeta platform sends these notifications to an endpoint hosted in your environment and configured to receive and process them. See the About Webhooks guide for more information.

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.

Create webhook
Copy section link
Copy section link

Action: POST
Endpoint: /webhooks

POST

Creates a webhook.

Request body
Copy section link
Copy section link

Fields Description

Fields	Description
token string Optional	Unique identifier of the webhook. If you do not include a token, the system automatically generates one. This token is necessary for use in other API calls. It is recommended that, rather than let the system, you create a simple, easy-to-remember string. This value cannot be updated. Allowable Values: 36 char max
name string Required	Descriptive name of the webhook. Allowable Values: 64 char max
active boolean Optional	Indicates whether the webhook is active. Allowable Values: `true`, `false` Default value: `true`
config object Required	Contains the configuration information for the webhook. Allowable Values: See The config object (request).
events array of strings Required	Specifies the types of events for which notifications are sent. Use the wildcard character `` to receive all notifications, or all notifications of a specified category. For example, enter `\` to receive all webhook notifications, or enter `transaction.` to receive all `transaction` webhook notifications. Allowable Values:* For a comprehensive list of events, see Event Types.

token

string
Optional

Unique identifier of the webhook.

If you do not include a token, the system automatically generates one. This token is necessary for use in other API calls. It is recommended that, rather than let the system, you create a simple, easy-to-remember string. This value cannot be updated.

Allowable Values:

36 char max

name

string
Required

Descriptive name of the webhook.

Allowable Values:

64 char max

active

boolean
Optional

Indicates whether the webhook is active.

Allowable Values:

true, false

Default value:
true

config

object
Required

Contains the configuration information for the webhook.

Allowable Values:

See The config object (request).

events

array of strings
Required

Specifies the types of events for which notifications are sent.

Use the wildcard character * to receive all notifications, or all notifications of a specified category. For example, enter \* to receive all webhook notifications, or enter transaction.* to receive all transaction webhook notifications.

Allowable Values:

For a comprehensive list of events, see Event Types.

The config object (request)
Copy section link
Copy section link

Fields Description

Fields	Description
url string Required	URL of your webhook endpoint. Allowable Values: 255 char max Must be HTTPS Empty string not allowed
secret string Optional	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 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
basic_auth_username string Required	Username for accessing your webhook endpoint. Allowable Values: 50 char max
basic_auth_password string Required	Password for accessing your webhook endpoint. Allowable Values: 20-50 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
custom_header object Optional	Contains information about the webhook’s custom HTTP headers for outgoing calls. Allowable Values: See The config.custom_header object (request).

url

string
Required

URL of your webhook endpoint.

Allowable Values:

255 char max
Must be HTTPS
Empty string not allowed

secret

string
Optional

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 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

basic_auth_username

string
Required

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string
Required

Password for accessing your webhook endpoint.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

custom_header

object
Optional

Contains information about the webhook’s custom HTTP headers for outgoing calls.

Allowable Values:

See The config.custom_header object (request).

The config.custom_header object (request)
Copy section link
Copy section link

Fields Description

Fields	Description
my_header_name_1 my_header_name_2 my_header_name_3 string Optional	Additional information included in the HTTP header for webhook notifications. For example, this might contain security information, along with Basic Authentication, when making a JIT Funding request. You can define the name and value of up to three headers, as shown below: Copied Is this helpful? Yes No Allowable Values: Up to three name-value pairs 500 char max per name 500 char max per value

my_header_name_1
my_header_name_2
my_header_name_3

string
Optional

Additional information included in the HTTP header for webhook notifications. For example, this might contain security information, along with Basic Authentication, when making a JIT Funding request.

You can define the name and value of up to three headers, as shown below:

Copied

Is this helpful?

Yes

Allowable Values:

Up to three name-value pairs
500 char max per name
500 char max per value

Response body
Copy section link
Copy section link

Fields Description

Fields	Description
token string Returned	Unique identifier of the webhook. If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated. Allowable Values: 36 char max
name string Returned	Descriptive name of the webhook. Allowable Values: 64 char max
active boolean Conditionally returned	Indicates whether the webhook is active. This field is returned if you included it in your webhook. Allowable Values: `true`, `false`
config object Returned	Contains the configuration information for the webhook. Allowable Values: See The config object (response).
events array of strings Returned	Specifies the types of events for which notifications are sent. The wildcard character `` indicates that you receive all webhook notifications, or all notifications of a specified category. For example, `\` indicates that you receive all webhook notifications; `transaction.` indicates that you receive all `transaction` webhook notifications. Allowable Values:* For a comprehensive list of events, see Event Types.
created_time datetime Returned	Time when the webhook event was created. Allowable Values: Valid timestamp
last_modified_time datetime Returned	Time when the associated object was last modified. Allowable Values: Valid timestamp

token

string
Returned

Unique identifier of the webhook.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

36 char max

name

string
Returned

Descriptive name of the webhook.

Allowable Values:

64 char max

active

boolean
Conditionally returned

Indicates whether the webhook is active. This field is returned if you included it in your webhook.

Allowable Values:

true, false

config

object
Returned

Contains the configuration information for the webhook.

Allowable Values:

See The config object (response).

events

array of strings
Returned

Specifies the types of events for which notifications are sent.

The wildcard character * indicates that you receive all webhook notifications, or all notifications of a specified category. For example, \* indicates that you receive all webhook notifications; transaction.* indicates that you receive all transaction webhook notifications.

Allowable Values:

For a comprehensive list of events, see Event Types.

created_time

datetime
Returned

Time when the webhook event was created.

Allowable Values:

Valid timestamp

last_modified_time

datetime
Returned

Time when the associated object was last modified.

Allowable Values:

Valid timestamp

The config object (response)
Copy section link
Copy section link

Fields Description

Fields	Description
url string Returned	URL of your webhook endpoint. Allowable Values: 255 char max Must be HTTPS Empty string not allowed
secret string Conditionally returned	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 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
basic_auth_username string Returned	Username for accessing your webhook endpoint. Allowable Values: 50 char max
basic_auth_password string Returned	Password for accessing your webhook endpoint. Allowable Values: 20-50 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
custom_header object Conditionally returned	Contains information about the webhook’s custom HTTP headers for outgoing calls. This object is returned if you included it in your `config` object. Allowable Values: See The config.custom_header object (response).

url

string
Returned

URL of your webhook endpoint.

Allowable Values:

255 char max
Must be HTTPS
Empty string not allowed

secret

string
Conditionally returned

A randomly chosen string used for implementing HMAC-SHA1.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

basic_auth_username

string
Returned

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string
Returned

Password for accessing your webhook endpoint.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

custom_header

object
Conditionally returned

Contains information about the webhook’s custom HTTP headers for outgoing calls. This object is returned if you included it in your config object.

Allowable Values:

See The config.custom_header object (response).

The config.custom_header object (response)
Copy section link
Copy section link

Fields Description

Fields	Description
my_header_name_1 my_header_name_2 my_header_name_3 string Conditionally returned	Additional customizable information included in the HTTP header. This string is returned if you included it in your `config.custom_header` object. Allowable Values: Up to three name-value pairs 500 char max per name 500 char max per value

my_header_name_1
my_header_name_2
my_header_name_3

string
Conditionally returned

Additional customizable information included in the HTTP header. This string is returned if you included it in your config.custom_header object.

Allowable Values:

Up to three name-value pairs
500 char max per name
500 char max per value

Sample request body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Sample response body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Retrieve webhook
Copy section link
Copy section link

Action: GET
Endpoint: /webhooks/{token}

GET

Retrieves a webhook.

URL path parameters
Copy section link
Copy section link

Fields Description

Fields	Description
token string Required	Identifies the webhook to retrieve. Allowable Values: Existing webhook token. Send a `GET` request to `/webhooks` to retrieve webhook tokens.

token

string
Required

Identifies the webhook to retrieve.

Allowable Values:

Existing webhook token.

Send a GET request to /webhooks to retrieve webhook tokens.

Response body
Copy section link
Copy section link

Fields Description

Fields	Description
token string Returned	Identifies the webhook to retrieve. If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated. Allowable Values: Existing webhook token.
name string Returned	Descriptive name of the webhook. Allowable Values: 64 char max
active boolean Conditionally returned	Indicates whether the webhook is active. This field is returned if you included it in your webhook object. Allowable Values: `true`, `false`
config object Returned	Contains the configuration information for the webhook. Allowable Values: See The config object (response).
events array of strings Returned	Specifies the types of events for which notifications are sent. The wildcard character `` indicates that you receive all webhook notifications, or all notifications of a specified category. For example, `\` indicates that you receive all webhook notifications; `transaction.` indicates that you receive all `transaction` webhook notifications. Allowable Values:* For a comprehensive list of events, see Event Types.
created_time datetime Returned	Time when the webhook event was created. Allowable Values: Valid timestamp
last_modified_time datetime Returned	Time when the associated object was last modified. Allowable Values: Valid timestamp

token

string
Returned

Identifies the webhook to retrieve.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

Existing webhook token.

name

string
Returned

Descriptive name of the webhook.

Allowable Values:

64 char max

active

boolean
Conditionally returned

Indicates whether the webhook is active. This field is returned if you included it in your webhook object.

Allowable Values:

true, false

config

object
Returned

Contains the configuration information for the webhook.

Allowable Values:

See The config object (response).

events

array of strings
Returned

Specifies the types of events for which notifications are sent.

Allowable Values:

For a comprehensive list of events, see Event Types.

created_time

datetime
Returned

Time when the webhook event was created.

Allowable Values:

Valid timestamp

last_modified_time

datetime
Returned

Time when the associated object was last modified.

Allowable Values:

Valid timestamp

Sample response body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Update webhook
Copy section link
Copy section link

Action: PUT
Endpoint: /webhooks/{token}

PUT

Updates a webhook.

URL path parameters
Copy section link
Copy section link

Fields Description

Fields	Description
token string Required	Identifies the webhook to update. Allowable Values: Existing webhook token. Send a `GET` request to `/webhooks` to retrieve webhook tokens.

token

string
Required

Identifies the webhook to update.

Allowable Values:

Existing webhook token.

Send a GET request to /webhooks to retrieve webhook tokens.

Request body
Copy section link
Copy section link

Fields Description

Fields	Description
name string Required	Descriptive name of the webhook. Allowable Values: 64 char max
active boolean Optional	Indicates whether the webhook is active. Allowable Values: `true`, `false` Default value: `true`
config object Required	Contains the configuration information for the webhook. Allowable Values: See The config object (request).
events array of strings Required	Specifies the types of events for which notifications are sent. Use the wildcard character `` to receive all notifications, or all notifications of a specified category. For example, enter `\` to receive all webhook notifications, or enter `transaction.` to receive all `transaction` webhook notifications. Allowable Values:* For a comprehensive list of events, see Event Types.

name

string
Required

Descriptive name of the webhook.

Allowable Values:

64 char max

active

boolean
Optional

Indicates whether the webhook is active.

Allowable Values:

true, false

Default value:
true

config

object
Required

Contains the configuration information for the webhook.

Allowable Values:

See The config object (request).

events

array of strings
Required

Specifies the types of events for which notifications are sent.

Allowable Values:

For a comprehensive list of events, see Event Types.

The config object (request)
Copy section link
Copy section link

Fields Description

Fields	Description
url string Required	URL of your webhook endpoint. Allowable Values: 255 char max Must be HTTPS Empty string not allowed
secret string Optional	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 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
basic_auth_username string Required	Username for accessing your webhook endpoint. Allowable Values: 50 char max
basic_auth_password string Required	Password for accessing your webhook endpoint. Allowable Values: 20-50 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
custom_header object Optional	Contains information about the webhook’s custom HTTP headers for outgoing calls. Allowable Values: See The config.custom_header object (request).

url

string
Required

URL of your webhook endpoint.

Allowable Values:

255 char max
Must be HTTPS
Empty string not allowed

secret

string
Optional

A randomly chosen string used for implementing HMAC-SHA1.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

basic_auth_username

string
Required

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string
Required

Password for accessing your webhook endpoint.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

custom_header

object
Optional

Contains information about the webhook’s custom HTTP headers for outgoing calls.

Allowable Values:

See The config.custom_header object (request).

The config.custom_header object (request)
Copy section link
Copy section link

Fields Description

Fields	Description
my_header_name_1 my_header_name_2 my_header_name_3	Additional information included in the HTTP header for webhook notifications. For example, this might contain security information, along with Basic Authentication, when making a JIT Funding request. You can define the name and value of up to three headers, as shown below: Copied Is this helpful? Yes No Allowable Values: Up to three name-value pairs 500 char max per name 500 char max per value

my_header_name_1
my_header_name_2
my_header_name_3

Additional information included in the HTTP header for webhook notifications. For example, this might contain security information, along with Basic Authentication, when making a JIT Funding request.

You can define the name and value of up to three headers, as shown below:

Copied

Is this helpful?

Yes

Allowable Values:

Up to three name-value pairs
500 char max per name
500 char max per value

Response body
Copy section link
Copy section link

Fields Description

Fields	Description
token string Returned	Unique identifier of the webhook. If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated. Allowable Values: 36 char max
name string Returned	Descriptive name of the webhook. Allowable Values: 64 char max
active boolean Conditionally returned	Indicates whether the webhook is active. This field is returned if you included it in your webhook object. Allowable Values: `true`, `false`
config object Returned	Contains the configuration information for the webhook. Allowable Values: See The config object (response).
events array of strings Returned	Specifies the types of events for which notifications are sent. The wildcard character `` indicates that you receive all webhook notifications, or all notifications of a specified category. For example, `\` indicates that you receive all webhook notifications; `transaction.` indicates that you receive all `transaction` webhook notifications. Allowable Values:* For a comprehensive list of events, see Event Types.
created_time datetime Returned	Time when the webhook event was created. Allowable Values: Valid timestamp
last_modified_time datetime Returned	Time when the associated object was last modified. Allowable Values: Valid timestamp

token

string
Returned

Unique identifier of the webhook.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

36 char max

name

string
Returned

Descriptive name of the webhook.

Allowable Values:

64 char max

active

boolean
Conditionally returned

Indicates whether the webhook is active. This field is returned if you included it in your webhook object.

Allowable Values:

true, false

config

object
Returned

Contains the configuration information for the webhook.

Allowable Values:

See The config object (response).

events

array of strings
Returned

Specifies the types of events for which notifications are sent.

Allowable Values:

For a comprehensive list of events, see Event Types.

created_time

datetime
Returned

Time when the webhook event was created.

Allowable Values:

Valid timestamp

last_modified_time

datetime
Returned

Time when the associated object was last modified.

Allowable Values:

Valid timestamp

The config object (response)
Copy section link
Copy section link

Fields Description

Fields	Description
url string Returned	URL of your webhook endpoint. Allowable Values: 255 char max Must be HTTPS Empty string not allowed
secret string Conditionally returned	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 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
basic_auth_username string Returned	Username for accessing your webhook endpoint. Allowable Values: 50 char max
basic_auth_password string Returned	Password for accessing your webhook endpoint. Allowable Values: 20-50 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
custom_header object Conditionally returned	Contains information about the webhook’s custom HTTP headers for outgoing calls. This object is returned if you included it in your `config` object. Allowable Values: See The config.custom_header object (response).

url

string
Returned

URL of your webhook endpoint.

Allowable Values:

255 char max
Must be HTTPS
Empty string not allowed

secret

string
Conditionally returned

A randomly chosen string used for implementing HMAC-SHA1.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

basic_auth_username

string
Returned

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string
Returned

Password for accessing your webhook endpoint.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

custom_header

object
Conditionally returned

Contains information about the webhook’s custom HTTP headers for outgoing calls. This object is returned if you included it in your config object.

Allowable Values:

See The config.custom_header object (response).

The config.custom_header object (response)
Copy section link
Copy section link

Fields Description

Fields	Description
my_header_name_1 my_header_name_2 my_header_name_3	Additional customizable information included in the HTTP header. This string is returned if you included it in your `config.custom_header` object. Allowable Values: Up to three name-value pairs 500 char max per name 500 char max per value

my_header_name_1
my_header_name_2
my_header_name_3

Additional customizable information included in the HTTP header. This string is returned if you included it in your config.custom_header object.

Allowable Values:

Up to three name-value pairs
500 char max per name
500 char max per value

Sample request body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Sample response body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Update webhook custom headers
Copy section link
Copy section link

Action: PUT
Endpoint: /webhooks/customheaders/{token}

PUT

Adds or updates a webhook’s custom HTTP headers.

URL path parameters
Copy section link
Copy section link

Fields Description

Fields	Description
token string Required	Identifies the webhook whose custom HTTP headers you want to update. Allowable Values: Existing webhook token. Send a `GET` request to `/webhooks` to retrieve webhook tokens.

token

string
Required

Identifies the webhook whose custom HTTP headers you want to update.

Allowable Values:

Existing webhook token.

Send a GET request to /webhooks to retrieve webhook tokens.

Request body
Copy section link
Copy section link

Fields	Description
custom_header object Required	Contains information about the webhook’s custom HTTP headers for outgoing calls. Allowable Values: See The config.custom_header object (request).

Fields

Description

custom_header

object
Required

Contains information about the webhook’s custom HTTP headers for outgoing calls.

Allowable Values:

See The config.custom_header object (request).

The config.custom_header object (request)
Copy section link
Copy section link

Fields Description

Fields	Description
my_header_name_1 my_header_name_2 my_header_name_3	Additional information included in the HTTP header for webhook notifications. For example, this might contain security information, along with Basic Authentication, when making a JIT Funding request. You can define the name and value of up to three headers, as shown below: Copied Is this helpful? Yes No Allowable Values: Up to three name-value pairs 500 char max per name 500 char max per value

my_header_name_1
my_header_name_2
my_header_name_3

Additional information included in the HTTP header for webhook notifications. For example, this might contain security information, along with Basic Authentication, when making a JIT Funding request.

You can define the name and value of up to three headers, as shown below:

Copied

Is this helpful?

Yes

Allowable Values:

Up to three name-value pairs
500 char max per name
500 char max per value

Response body
Copy section link
Copy section link

Fields Description

Fields	Description
token string Returned	Unique identifier of the webhook. If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated. Allowable Values: 36 char max
name string Returned	Descriptive name of the webhook. Allowable Values: 64 char max
active boolean Conditionally returned	Indicates whether the webhook is active. This field is returned if you included it in your webhook object. Allowable Values: `true`, `false` Default value: `true`
config object Returned	Contains the configuration information for the webhook. Allowable Values: See The config object (response).
events array of strings Returned	Specifies the types of events for which notifications are sent. The wildcard character `` indicates that you receive all webhook notifications, or all notifications of a specified category. For example, `\` indicates that you receive all webhook notifications; `transaction.` indicates that you receive all `transaction` webhook notifications. Allowable Values:* For a comprehensive list of events, see Event Types.
created_time datetime Returned	Time when the webhook event was created. Allowable Values: Valid timestamp
last_modified_time datetime Returned	Time when the associated object was last modified. Allowable Values: Valid timestamp

token

string
Returned

Unique identifier of the webhook.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

36 char max

name

string
Returned

Descriptive name of the webhook.

Allowable Values:

64 char max

active

boolean
Conditionally returned

Indicates whether the webhook is active. This field is returned if you included it in your webhook object.

Allowable Values:

true, false

Default value:
true

config

object
Returned

Contains the configuration information for the webhook.

Allowable Values:

See The config object (response).

events

array of strings
Returned

Specifies the types of events for which notifications are sent.

Allowable Values:

For a comprehensive list of events, see Event Types.

created_time

datetime
Returned

Time when the webhook event was created.

Allowable Values:

Valid timestamp

last_modified_time

datetime
Returned

Time when the associated object was last modified.

Allowable Values:

Valid timestamp

The config object (response)
Copy section link
Copy section link

Fields Description

Fields	Description
url string Returned	URL of your webhook endpoint. Allowable Values: 255 char max Must be HTTPS Empty string not allowed
secret string Optional	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 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
basic_auth_username string Required	Username for accessing your webhook endpoint. Allowable Values: 50 char max
basic_auth_password string Required	Password for accessing your webhook endpoint. Allowable Values: 20-50 characters Must contain at least one numeral Must contain at least one lowercase letter Must contain at least one uppercase letter Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?
custom_header object Returned	Contains information about the webhook’s custom HTTP headers for outgoing calls. This object is returned if you included it in your `config` object. Allowable Values: See The config.custom_header object (response).

url

string
Returned

URL of your webhook endpoint.

Allowable Values:

255 char max
Must be HTTPS
Empty string not allowed

secret

string
Optional

A randomly chosen string used for implementing HMAC-SHA1.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

basic_auth_username

string
Required

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string
Required

Password for accessing your webhook endpoint.

Allowable Values:

20-50 characters
Must contain at least one numeral
Must contain at least one lowercase letter
Must contain at least one uppercase letter
Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

custom_header

object
Returned

Contains information about the webhook’s custom HTTP headers for outgoing calls. This object is returned if you included it in your config object.

Allowable Values:

See The config.custom_header object (response).

The config.custom_header object (response)
Copy section link
Copy section link

Fields Description

Fields	Description
my_header_name_1 my_header_name_2 my_header_name_3	Additional customizable information included in the HTTP header. This string is returned if you included it in your `config.custom_header` object. Allowable Values: Up to three name-value pairs 500 char max per name 500 char max per value

my_header_name_1
my_header_name_2
my_header_name_3

Additional customizable information included in the HTTP header. This string is returned if you included it in your config.custom_header object.

Allowable Values:

Up to three name-value pairs
500 char max per name
500 char max per value

Sample request body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Sample response body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

List webhooks
Copy section link
Copy section link

Action: GET
Endpoint: /webhooks

GET

Returns an array of all webhooks.

This endpoint supports field filtering, sorting, and pagination.

Sample response body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Ping webhook
Copy section link
Copy section link

Action: POST
Endpoint: /webhooks/{token}/ping

POST

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
Copy section link
Copy section link

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:

Copied

Is this helpful?

Yes

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:

Copied

Is this helpful?

Yes

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
Copy section link
Copy section link

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:

Copied

Is this helpful?

Yes

The following chain of actions occurs during a successful ping:

The Marqeta platform receives the ping request (POST to /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> is an optional message):

Copied

Is this helpful?

Yes

Failed pings are not automatically retried.

Sample request body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Sample response body
Copy section link
Copy section link

Copied

Is this helpful?

Yes

Resend event notification
Copy section link
Copy section link

Action: POST
Endpoint: /webhooks/{token}/{event_type}/{event_token}

POST

Resends an event notification to your webhook endpoint.

Although you send this request as a POST, all parameters are on 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
Copy section link

Fields Description

Fields	Description
token string Required	The token identifying the webhook object that is configured to send event notifications to your webhook endpoint. Allowable Values: Existing webhook token. Send a `GET` request to `/webhooks` to retrieve webhook tokens.
event_type string Required	Specifies the type of event you want to resend. Allowable Values: `usertransition`, `businesstransition`, `cardtransition`, `transaction`, `digitalwallettokentransition`, `chargebacktransition`, `commandomodetransition`, `casetransition`, `directdeposittransition`, `banktransfertransition`
event_token string Required	The token identifying the event for which you want to resend a notification. Allowable Values: Existing event token. Send a `GET` request to `/usertransitions/user/{token}` to retrieve transition tokens related to a particular user. Send a `GET` request to `/businesstransitions/business/{token}` to retrieve transition tokens related to a particular business. Send a `GET` request to `/cardtransitions/card/{card_token}` to retrieve transition tokens related to a particular card. Send a `GET` request to `/transactions` to retrieve transaction tokens. Send a `GET` request to `/digitalwallettokentransitions/digitalwallettoken/{token}` to retrieve transition tokens related to a particular digital wallet token. Send a `GET` request to `/commandomodes/{commandomode_token}/transitions` to retrieve Commando Mode transition tokens related to a particular Commando Mode control set. Send a `GET` request to `/cases/{token}/transitions` to retrieve case transition tokens related to a particular case. Send a `GET` request to `/directdeposit/transitions/{token}` to retrieve a transition related to a particular direct deposit account.

token

string
Required

The token identifying the webhook object that is configured to send event notifications to your webhook endpoint.

Allowable Values:

Existing webhook token.

Send a GET request to /webhooks to retrieve webhook tokens.

event_type

string
Required

Specifies the type of event you want to resend.

Allowable Values:

usertransition, businesstransition, cardtransition, transaction, digitalwallettokentransition, chargebacktransition, commandomodetransition, casetransition, directdeposittransition, banktransfertransition

event_token

string
Required

The token identifying the event for which you want to resend a notification.

Allowable Values:

Existing event token.

Send a GET request to /usertransitions/user/{token} to retrieve transition tokens related to a particular user.
Send a GET request to /businesstransitions/business/{token} to retrieve transition tokens related to a particular business.
Send a GET request to /cardtransitions/card/{card_token} to retrieve transition tokens related to a particular card.
Send a GET request to /transactions to retrieve transaction tokens.
Send a GET request to /digitalwallettokentransitions/digitalwallettoken/{token} to retrieve transition tokens related to a particular digital wallet token.
Send a GET request to /commandomodes/{commandomode_token}/transitions to retrieve Commando Mode transition tokens related to a particular Commando Mode control set.
Send a GET request to /cases/{token}/transitions to retrieve case transition tokens related to a particular case.
Send a GET request to /directdeposit/transitions/{token} to retrieve a transition related to a particular direct deposit account.

Sample response bodies
Copy section link
Copy section link

The following sample response body shows a successful resend of an event notification.

Copied

Is this helpful?

Yes

An incorrectly entered card number with a BIN prefix coincidentally associated with your program can return failure codes such as those shown in the following response:

Copied

Is this helpful?

Yes

Core API Reference

Core API Explorer

DiVA API Reference