Webhooks

Webhooks are notifications about API events, sent as they occur. The Marqeta platform sends these notifications to an endpoint that is hosted in your environment and configured to receive and process them. Create a webhook object to represent your webhook endpoint. Configure it with the URL of your webhook endpoint and a set of credentials for accessing that endpoint. You can configure it to send notifications for a single event, a group of events by type, or all event types. To set up multiple webhook endpoints and route different types of event notifications to each, create multiple webhook objects and configure each to send a specific type of event notification to a specific endpoint. See About Webhooks for information on notifications and a tutorial that walks you through the configuration of your webhook endpoint. See Event Types for reference documentation on the types of events that the Marqeta platform supports.

Note
Webhooks URLs are cached. Changes made on your webhook endpoint can take up to one hour to be applied.

Create webhook

Action: POST
Endpoint: /webhooks Creates a webhook.

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

{
  "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

{
  "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, 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.

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

{
  "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"
    }
  ]
}

Update webhook custom headers

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

{
  "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

{
  "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.

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 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

{
  "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 for a code example that identifies a ping request). The response can optionally include a JSON-formatted body, for example:

JSON

{"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-formatted body in the request, that is:

JSON

{}

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 <optional message> represents additional details you can choose to include in the response):

JSON

{
  "error_message": "Webhook operation failed " + <optional message>,
  "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

{
  "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

​Create webhook

​Request body

​Sample request body

​Response body

​Sample response body

​List webhooks

​URL query parameters

​Response body

​Sample response body

​Update webhook custom headers

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​Retrieve webhook

​URL path parameters

​Response body

​Update webhook

​URL path parameters

​Request body

​Response body

​Ping webhook

​Configuring your webhook endpoint

​Using the ping facility

​URL path parameters

​Response body

​Sample response body

​Resend event notification

​URL path parameters

Create webhook

Request body

Sample request body

Response body

Sample response body

List webhooks

URL query parameters

Response body

Sample response body

Update webhook custom headers

URL path parameters

Request body

Sample request body

Response body

Sample response body

Retrieve webhook

URL path parameters

Response body

Update webhook

URL path parameters

Request body

Response body

Ping webhook

Configuring your webhook endpoint

Using the ping facility

URL path parameters

Response body

Sample response body

Resend event notification

URL path parameters