> ## 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.
# Webhooks
> Use webhooks to send notifications about API events as they occur.
export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
text: "mint-text-green-700 dark:mint-text-green-400",
border: "mint-border-green-300 dark:mint-border-green-700"
},
POST: {
bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
text: "mint-text-blue-700 dark:mint-text-blue-400"
},
PUT: {
bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
text: "mint-text-yellow-700 dark:mint-text-yellow-400"
},
PATCH: {
bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
text: "mint-text-orange-700 dark:mint-text-orange-400"
},
DELETE: {
bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
text: "mint-text-red-700 dark:mint-text-red-400"
},
API: {
bg: "mint-bg-black",
text: "mint-text-white"
}
};
const MethodBadge = ({method}) => {
const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
return
{method?.toUpperCase()}
;
};
const content =
{}
{}
{title}
{children &&
{children}
}
Create webhook
**Action:** `POST`\
**Endpoint:** `/webhooks`
{/* */}
Creates a webhook.
**Note**\
As shown in the example, `config.secret`, `config.basic_auth_username`, and `config.basic_auth_password` are masked in responses to this and all other requests. To access these values later, store them securely before making the request.
Request body
| Fields | Description |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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:**
`basic_auth_password`, `basic_auth_username`, `custom_header`, `secret`, `url`, `use_mtls` |
| config.**basic\_auth\_password**
string
Required | Password for accessing your webhook endpoint.
**Allowable Values:**
20–50 chars
- 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:
`@``#``$``%``!``^``&``\*``(``)`
`\\``_``+``~``-``=``[``]``\{``}`
`,``;``:``'``"``.``/``<``>``?`\` |
| config.**basic\_auth\_username**
string
Required | Username for accessing your webhook endpoint.
**Allowable Values:**
1–50 chars |
| config.**custom\_header**
object
Optional | 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
Optional | Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256, depending on the value included in the `signature_algorithm` field. A signature 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
- 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:
`@``#``$``%``!``^``&``\*``(``)`
`\\``_``+``~``-``=``[``]``\{``}`
`,``;``:``'``"``.``/``<``>``?`\` |
| config.**signature\_algorithm**
string
Optional | Algorithm used for signature verification. A signature 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:**
1–20 chars
- Value must be either `HMAC_SHA_1` (legacy) or `HMAC_SHA_256` (recommended).
- You must specify this value if `secret` is specified. |
| config.**url**
string
Required | URL of your webhook endpoint.
**Allowable Values:**
1–255 chars
- Must be HTTPS
- Empty string not allowed |
| config.**use\_mtls**
boolean
Optional | Set to `true` to use use mutual transport layer security (mTLS) authentication for the webhook.
mTLS authentication is in the beta testing phase, and is not yet generally available. Contact your Marqeta representative for more information about using mTLS authentication.
**Allowable Values:**
`true`, `false` |
| events
array of strings
Required | 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.
**NOTE:** 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.\*`.
**Allowable Values:**
For a comprehensive list of events, see Event Types. |
| name
string
Required | Descriptive name of the webhook.
**Allowable Values:**
1–64 chars |
| token
string
Optional | Unique identifier of the webhook.
**Allowable Values:**
1–36 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"token": "my_webhook_token",
"active": true,
"events": [
"*"
],
"config": {
"url": "https://my_secure_domain.com/webhook",
"secret": "my_20-character-min_secret",
"signature_algorithm": "HMAC_SHA_256",
"basic_auth_username": "my_username",
"basic_auth_password": "my_20-to-50-character_password",
"custom_header": {
"my_header_name_1": "my_value_1",
"my_header_name_2": "my_value_2"
}
},
"name": "my_webhook_name"
}
```
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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:**
`basic_auth_password`, `basic_auth_username`, `custom_header`, `secret`, `url`, `use_mtls` |
| config.**basic\_auth\_password**
string
Returned | Password for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the password, followed by 10 asterisks and the last character of the password. |
| config.**basic\_auth\_username**
string
Returned | Username for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the username, followed by 10 asterisks and the last character of the username. |
| config.**custom\_header**
object
Conditionally returned | 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
Conditionally returned | Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256, depending on the value included in the `signature_algorithm` field. A signature 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:**
12 chars
The first character of the secret, followed by 10 asterisks and the last character of the secret. |
| config.**signature\_algorithm**
string
Conditionally returned | Algorithm used for signature verification. A signature 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:**
1–20 chars
- Value must be either `HMAC_SHA_1` (legacy) or `HMAC_SHA_256` (recommended).
- You must specify this value if `secret` is specified. |
| config.**url**
string
Returned | URL of your webhook endpoint.
**Allowable Values:**
1–255 chars
- Must be HTTPS
- Empty string not allowed |
| config.**use\_mtls**
boolean
Conditionally returned | Set to `true` to use use mutual transport layer security (mTLS) authentication for the webhook.
mTLS authentication is in the beta testing phase, and is not yet generally available. Contact your Marqeta representative for more information about using mTLS authentication.
**Allowable Values:**
`true`, `false` |
| created\_time
datetime
Conditionally returned | Date and time when the webhook event was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| 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.
**NOTE:** 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.\*`.
**Allowable Values:**
For a comprehensive list of events, see Event Types. |
| last\_modified\_time
datetime
Conditionally returned | Date and time when the associated object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| name
string
Returned | Descriptive name of the webhook.
**Allowable Values:**
1–64 chars |
| token
string
Conditionally returned | Unique identifier of the webhook.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"name": "my_webhook_name",
"active": true,
"config": {
"url": "https://my_secure_domain.com/webhook",
"secret": "m**********t",
"signature_algorithm": "HMAC_SHA_256",
"basic_auth_username": "m**********e",
"basic_auth_password": "m**********d",
"custom_header": {
"my_header_name_1": "my_value_1",
"my_header_name_2": "my_value_2"
}
},
"events": [
"*"
],
"token": "my_webhook_token",
"created_time": "2023-02-24T23:20:28Z",
"last_modified_time": "2023-02-24T23:20:28Z"
}
```
List webhooks
**Action:** `GET`\
**Endpoint:** `/webhooks`
{/* */}
Returns an array of all webhooks.
This endpoint supports [field filtering](/core-api/field-filtering/), [sorting](/core-api/sorting-and-pagination/), and [pagination](/core-api/sorting-and-pagination/).
**Note**\
As shown in the example, `config.secret`, `config.basic_auth_username`, and `config.basic_auth_password` are masked in responses to this and all other requests. To ensure that you can access these values as needed, update them on your endpoint, store them securely, and then [update the webhook subscription](/core-api/webhooks/#put_webhooks_token).
URL query parameters
| Fields | Description |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| active
boolean
Optional | Set to `true` to return only active webhook configurations, otherwise all webhook configurations will be returned.
**Allowable Values:**
`true`, `false` |
| count
integer
Optional | Number of resources to retrieve.
**Allowable Values:**
1-10
**Default value:**
5 |
| start\_index
integer
Optional | Sort order index of the first resource in the returned array.
**Allowable Values:**
Any integer
**Default value:**
0 |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model
**Default value:**
`-createdTime` |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of resources to retrieve.
This field is returned if there are resources in your returned array.
**Allowable Values:**
1-10 |
| data
array of objects
Conditionally returned | Array of webhooks resources.
Resources are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more webhook objects |
| data\[].**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` |
| data\[].**config**
object
Returned | Contains the configuration information for the webhook.
**Allowable Values:**
`basic_auth_password`, `basic_auth_username`, `custom_header`, `secret`, `url`, `use_mtls` |
| data\[].config.**basic\_auth\_password**
string
Returned | Password for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the password, followed by 10 asterisks and the last character of the password. |
| data\[].config.**basic\_auth\_username**
string
Returned | Username for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the username, followed by 10 asterisks and the last character of the username. |
| data\[].config.**custom\_header**
object
Conditionally returned | 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
Conditionally returned | Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256, depending on the value included in the `signature_algorithm` field. A signature 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:**
12 chars
The first character of the secret, followed by 10 asterisks and the last character of the secret. |
| data\[].config.**signature\_algorithm**
string
Conditionally returned | Algorithm used for signature verification. A signature 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:**
1–20 chars
- Value must be either `HMAC_SHA_1` (legacy) or `HMAC_SHA_256` (recommended).
- You must specify this value if `secret` is specified. |
| data\[].config.**url**
string
Returned | URL of your webhook endpoint.
**Allowable Values:**
1–255 chars
- Must be HTTPS
- Empty string not allowed |
| data\[].config.**use\_mtls**
boolean
Conditionally returned | Set to `true` to use use mutual transport layer security (mTLS) authentication for the webhook.
mTLS authentication is in the beta testing phase, and is not yet generally available. Contact your Marqeta representative for more information about using mTLS authentication.
**Allowable Values:**
`true`, `false` |
| data\[].**created\_time**
datetime
Conditionally returned | Date and time when the webhook event was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**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.
**NOTE:** 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.\*`.
**Allowable Values:**
For a comprehensive list of events, see Event Types. |
| data\[].**last\_modified\_time**
datetime
Conditionally returned | Date and time when the associated object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**name**
string
Returned | Descriptive name of the webhook.
**Allowable Values:**
1–64 chars |
| data\[].**token**
string
Conditionally returned | Unique identifier of the webhook.
**Allowable Values:**
1–36 chars |
| end\_index
integer
Conditionally returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| is\_more
boolean
Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| start\_index
integer
Conditionally returned | Sort order index of the first resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": true,
"data": [
{
"name": "my_webhook_name",
"active": true,
"config": {
"url": "https://my_secure_domain.com/webhook",
"secret": "m**********t",
"signature_algorithm": "HMAC_SHA_256",
"basic_auth_username": "m**********e",
"basic_auth_password": "m**********d",
"custom_header": {
"my_header_name_1": "my_value_1",
"my_header_name_2": "my_value_2",
"my_header_name_3": "my_value_3"
}
},
"events": [
"*"
],
"token": "my_webhook_token",
"created_time": "2023-02-24T23:20:28Z",
"last_modified_time": "2023-02-24T23:20:28Z"
}
]
}
```
**Action:** `PUT`\
**Endpoint:** `/webhooks/customheaders/{token}`
{/* */}
Adds or updates a webhook’s custom HTTP headers.
URL path parameters
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the webhook.
**Allowable Values:**
Existing webhook token |
Request body
| Fields | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| custom\_header
object
Optional | 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 |
Sample request body
```json JSON lines wrap theme={null}
{
"custom_header": {
"my_header_name_1": "my_value_1",
"my_header_name_2": "my_value_2",
"my_header_name_3": "my_value_3"
}
}
```
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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:**
`basic_auth_password`, `basic_auth_username`, `custom_header`, `secret`, `url`, `use_mtls` |
| config.**basic\_auth\_password**
string
Returned | Password for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the password, followed by 10 asterisks and the last character of the password. |
| config.**basic\_auth\_username**
string
Returned | Username for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the username, followed by 10 asterisks and the last character of the username. |
| config.**custom\_header**
object
Conditionally returned | 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
Conditionally returned | Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256, depending on the value included in the `signature_algorithm` field. A signature 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:**
12 chars
The first character of the secret, followed by 10 asterisks and the last character of the secret. |
| config.**signature\_algorithm**
string
Conditionally returned | Algorithm used for signature verification. A signature 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:**
1–20 chars
- Value must be either `HMAC_SHA_1` (legacy) or `HMAC_SHA_256` (recommended).
- You must specify this value if `secret` is specified. |
| config.**url**
string
Returned | URL of your webhook endpoint.
**Allowable Values:**
1–255 chars
- Must be HTTPS
- Empty string not allowed |
| config.**use\_mtls**
boolean
Conditionally returned | Set to `true` to use use mutual transport layer security (mTLS) authentication for the webhook.
mTLS authentication is in the beta testing phase, and is not yet generally available. Contact your Marqeta representative for more information about using mTLS authentication.
**Allowable Values:**
`true`, `false` |
| created\_time
datetime
Conditionally returned | Date and time when the webhook event was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| 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.
**NOTE:** 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.\*`.
**Allowable Values:**
For a comprehensive list of events, see Event Types. |
| last\_modified\_time
datetime
Conditionally returned | Date and time when the associated object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| name
string
Returned | Descriptive name of the webhook.
**Allowable Values:**
1–64 chars |
| token
string
Conditionally returned | Unique identifier of the webhook.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"token": "my_webhook_01",
"name": "my_webhook_name",
"active": true,
"config": {
"url": "https://my_secure_domain.com/webhook",
"secret": "m**********t",
"signature_algorithm": "HMAC_SHA_256",
"basic_auth_username": "m**********e",
"basic_auth_password": "m**********d",
"custom_header": {
"my_header_name_1": "my_value_1",
"my_header_name_2": "my_value_2",
"my_header_name_3": "my_value_3"
}
},
"events": [
"transaction.*"
],
"created_time": "2023-02-06T08:12:32Z",
"last_modified_time": "2023-02-26T22:07:23Z"
}
```
Retrieve webhook
**Action:** `GET`\
**Endpoint:** `/webhooks/{token}`
{/* */}
Retrieves a webhook.
**Note**\
As shown in the example, `config.secret`, `config.basic_auth_username`, and `config.basic_auth_password` are masked in responses to this and all other requests. To ensure that you can access these values as needed, update them on your endpoint, store them securely, and then [update the webhook subscription](/core-api/webhooks/#put_webhooks_token).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the webhook.
**Allowable Values:**
Existing webhook token |
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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:**
`basic_auth_password`, `basic_auth_username`, `custom_header`, `secret`, `url`, `use_mtls` |
| config.**basic\_auth\_password**
string
Returned | Password for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the password, followed by 10 asterisks and the last character of the password. |
| config.**basic\_auth\_username**
string
Returned | Username for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the username, followed by 10 asterisks and the last character of the username. |
| config.**custom\_header**
object
Conditionally returned | 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
Conditionally returned | Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256, depending on the value included in the `signature_algorithm` field. A signature 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:**
12 chars
The first character of the secret, followed by 10 asterisks and the last character of the secret. |
| config.**signature\_algorithm**
string
Conditionally returned | Algorithm used for signature verification. A signature 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:**
1–20 chars
- Value must be either `HMAC_SHA_1` (legacy) or `HMAC_SHA_256` (recommended).
- You must specify this value if `secret` is specified. |
| config.**url**
string
Returned | URL of your webhook endpoint.
**Allowable Values:**
1–255 chars
- Must be HTTPS
- Empty string not allowed |
| config.**use\_mtls**
boolean
Conditionally returned | Set to `true` to use use mutual transport layer security (mTLS) authentication for the webhook.
mTLS authentication is in the beta testing phase, and is not yet generally available. Contact your Marqeta representative for more information about using mTLS authentication.
**Allowable Values:**
`true`, `false` |
| created\_time
datetime
Conditionally returned | Date and time when the webhook event was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| 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.
**NOTE:** 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.\*`.
**Allowable Values:**
For a comprehensive list of events, see Event Types. |
| last\_modified\_time
datetime
Conditionally returned | Date and time when the associated object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| name
string
Returned | Descriptive name of the webhook.
**Allowable Values:**
1–64 chars |
| token
string
Conditionally returned | Unique identifier of the webhook.
**Allowable Values:**
1–36 chars |
Update webhook
**Action:** `PUT`\
**Endpoint:** `/webhooks/{token}`
{/* */}
Updates a webhook.
You can also use this endpoint to disable webhooks you no longer want to receive—there is no `DELETE` method available to remove unneeded webhooks. To disable a webhook, use this endpoint to set its `active` field to `false`.
**Note**\
As shown in the example, `config.secret`, `config.basic_auth_username`, and `config.basic_auth_password` are masked in responses to this and all other requests. To access these values later, store them securely before making the request. When modifying authentication credentials, update the endpoint configuration before updating your webhook subscription to avoid missing any important event notifications.
For instructions on managing your webhooks via the Developer Dashboard, see the [Developer Tools](/developer-guides/developer-tools/#_to_disable_a_webhook) guide.
URL path parameters
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the webhook.
**Allowable Values:**
Existing webhook token |
Request body
| Fields | Description |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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:**
`basic_auth_password`, `basic_auth_username`, `custom_header`, `secret`, `url`, `use_mtls` |
| config.**basic\_auth\_password**
string
Required | Password for accessing your webhook endpoint.
**Allowable Values:**
20–50 chars
- 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:
`@``#``$``%``!``^``&``\*``(``)`
`\\``_``+``~``-``=``[``]``\{``}`
`,``;``:``'``"``.``/``<``>``?`\` |
| config.**basic\_auth\_username**
string
Required | Username for accessing your webhook endpoint.
**Allowable Values:**
1–50 chars |
| config.**custom\_header**
object
Optional | 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
Optional | Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256, depending on the value included in the `signature_algorithm` field. A signature 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
- 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:
`@``#``$``%``!``^``&``\*``(``)`
`\\``_``+``~``-``=``[``]``\{``}`
`,``;``:``'``"``.``/``<``>``?`\` |
| config.**signature\_algorithm**
string
Optional | Algorithm used for signature verification. A signature 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:**
1–20 chars
- Value must be either `HMAC_SHA_1` (legacy) or `HMAC_SHA_256` (recommended).
- You must specify this value if `secret` is specified. |
| config.**url**
string
Required | URL of your webhook endpoint.
**Allowable Values:**
1–255 chars
- Must be HTTPS
- Empty string not allowed |
| config.**use\_mtls**
boolean
Optional | Set to `true` to use use mutual transport layer security (mTLS) authentication for the webhook.
mTLS authentication is in the beta testing phase, and is not yet generally available. Contact your Marqeta representative for more information about using mTLS authentication.
**Allowable Values:**
`true`, `false` |
| events
array of strings
Required | 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.
**NOTE:** 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.\*`.
**Allowable Values:**
For a comprehensive list of events, see Event Types. |
| name
string
Required | Descriptive name of the webhook.
**Allowable Values:**
1–64 chars |
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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:**
`basic_auth_password`, `basic_auth_username`, `custom_header`, `secret`, `url`, `use_mtls` |
| config.**basic\_auth\_password**
string
Returned | Password for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the password, followed by 10 asterisks and the last character of the password. |
| config.**basic\_auth\_username**
string
Returned | Username for accessing your webhook endpoint.
**Allowable Values:**
12 chars
The first character of the username, followed by 10 asterisks and the last character of the username. |
| config.**custom\_header**
object
Conditionally returned | 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
Conditionally returned | Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256, depending on the value included in the `signature_algorithm` field. A signature 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:**
12 chars
The first character of the secret, followed by 10 asterisks and the last character of the secret. |
| config.**signature\_algorithm**
string
Conditionally returned | Algorithm used for signature verification. A signature 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:**
1–20 chars
- Value must be either `HMAC_SHA_1` (legacy) or `HMAC_SHA_256` (recommended).
- You must specify this value if `secret` is specified. |
| config.**url**
string
Returned | URL of your webhook endpoint.
**Allowable Values:**
1–255 chars
- Must be HTTPS
- Empty string not allowed |
| config.**use\_mtls**
boolean
Conditionally returned | Set to `true` to use use mutual transport layer security (mTLS) authentication for the webhook.
mTLS authentication is in the beta testing phase, and is not yet generally available. Contact your Marqeta representative for more information about using mTLS authentication.
**Allowable Values:**
`true`, `false` |
| created\_time
datetime
Conditionally returned | Date and time when the webhook event was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| 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.
**NOTE:** 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.\*`.
**Allowable Values:**
For a comprehensive list of events, see Event Types. |
| last\_modified\_time
datetime
Conditionally returned | Date and time when the associated object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| name
string
Returned | Descriptive name of the webhook.
**Allowable Values:**
1–64 chars |
| token
string
Conditionally returned | Unique identifier of the webhook.
**Allowable Values:**
1–36 chars |
Ping webhook
**Action:** `POST`\
**Endpoint:** `/webhooks/{token}/ping`
{/* */}
Pings your 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
When the Marqeta platform receives the ping request, it sends a `POST` request containing the following body to the URL of your webhook endpoint:
```json JSON lines wrap theme={null}
{
"pings": [
{
"token": "marqeta",
"payload": "healthcheck"
}
]
}
```
To indicate that it is functioning properly, your webhook endpoint must respond with a status code of `200` (see [Signature Verification](/developer-guides/signature-verification/) for a code example that identifies a ping request). The response can optionally include a [JSON](http://www.json.org/)-formatted body, for example:
```json JSON lines wrap theme={null}
{"my_endpoint_status": "alive"}
```
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 which webhook you want to reach. Include an empty, [JSON](http://www.json.org/)-formatted body in the request, that is:
```json JSON lines wrap theme={null}
{}
```
The following chain of actions occurs during the successful execution of a ping operation:
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 it 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 `` represents additional details you can choose to include in the response):
```json JSON lines wrap theme={null}
{
"error_message": "Webhook operation failed " + ,
"error_code": "422600"
}
```
Failed pings are not automatically retried.
URL path parameters
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the webhook.
**Allowable Values:**
Existing webhook token |
Response body
| Fields | Description |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| pings
array of objects
Returned | Array of ping requests to your webhook endpoint.
**Allowable Values:**
Valid array of one or more `ping` requests |
| pings\[].**payload**
string
Conditionally returned | Payload of the ping request.
**Allowable Values:**
255 char max |
| pings\[].**token**
string
Conditionally returned | Unique identifier of the ping request.
**Allowable Values:**
255 char max |
Sample response body
```json JSON lines wrap theme={null}
{
"pings": [
{
"my_endpoint_status": "alive"
}
]
}
```
Resend event notification
**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 is also returned in the response to this request.
URL path parameters
| Fields | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the webhook.
**Allowable Values:**
Existing webhook token |
| event\_type
string
Required | Specifies the type of event you want to resend.
**Allowable Values:**
`chargebacktransition`, `digitalwallettokentransition`, `cardtransition`, `usertransition`, `businesstransition`, `transaction` |
| event\_token
string
Required | Unique identifier of the event for which you want to resend a notification.
**Allowable Values:**
Existing event token |