POST/
Creates a webhook.
Note
As shown in the example,
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, falseDefault 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 event types that trigger notifications. Use the wildcard character * to subscribe to all webhook notifications or all notifications within a specific category. For example, transaction.* .Note: The wildcard character does not return L2 and L3 card data events. Note: Use the wildcard character only with the base type events ( cardtransition.*) not subcategories (cardtransition.fulfillment.*).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
{
"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 event types that trigger notifications. Use the wildcard character * to subscribe to all webhook notifications or all notifications within a specific category. For example, transaction.* .Note: The wildcard character does not return L2 and L3 card data events. Note: Use the wildcard character only with the base type events ( cardtransition.*) not subcategories (cardtransition.fulfillment.*).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
{
"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"
}