openapi: 3.0.3 info: contact: email: support@marqeta.com name: Marqeta description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta. termsOfService: https://www.marqeta.com/api-terms title: Core accepted countries Webhooks API version: 3.0.39 servers: - url: /v3 security: - mqAppAndAccessToken: [] tags: - description: '// Conditional snippet for beta or internal content include::../../maturity-admonition-banner.adoc[] 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 <> for information on notifications and a tutorial that walks you through the configuration of your webhook endpoint. See <> 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.' name: Webhooks paths: /webhooks: get: description: 'Returns an array of all webhooks. This endpoint supports <>, <>, and <>. [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 you can access these values as needed, update them on your endpoint, store them securely, and then <>.' operationId: getWebhooks parameters: - description: Set to `true` to return only active webhook configurations, otherwise all webhook configurations will be returned. explode: true in: query name: active required: false schema: default: false type: boolean style: form - description: Number of resources to retrieve. explode: true in: query name: count required: false schema: default: 5 format: int32 type: integer style: form - description: Sort order index of the first resource in the returned array. explode: true in: query name: start_index required: false schema: default: 0 format: int32 type: integer style: form - description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.' explode: true in: query name: fields required: false schema: type: string style: form - description: '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.' explode: true in: query name: sort_by required: false schema: default: -createdTime type: string style: form responses: '200': content: application/json: example: count: 1 data: - active: true config: basic_auth_password: m**********d basic_auth_username: m**********e custom_header: my_header_name_1: my_value_1 my_header_name_2: my_value_2 my_header_name_3: my_value_3 secret: m**********t signature_algorithm: HMAC_SHA_256 url: https://my_secure_domain.com/webhook created_time: 2023-02-24 23:20:28+00:00 events: - '*' last_modified_time: 2023-02-24 23:20:28+00:00 name: my_webhook_name token: my_webhook_token end_index: 0 is_more: true start_index: 0 schema: $ref: '#/components/schemas/WebhookResponseModelListResponse' description: Success '400': content: {} description: Bad request '500': content: {} description: Server error summary: List webhooks tags: - Webhooks post: description: '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.' operationId: postWebhooks requestBody: content: application/json: example: active: true config: basic_auth_password: my_20-to-50-character_password basic_auth_username: my_username custom_header: my_header_name_1: my_value_1 my_header_name_2: my_value_2 secret: my_20-character-min_secret signature_algorithm: HMAC_SHA_256 url: https://my_secure_domain.com/webhook events: - '*' name: my_webhook_name token: my_webhook_token schema: $ref: '#/components/schemas/webhook_request_model' required: false responses: '201': content: application/json: example: active: true config: basic_auth_password: m**********d basic_auth_username: m**********e custom_header: my_header_name_1: my_value_1 my_header_name_2: my_value_2 secret: m**********t signature_algorithm: HMAC_SHA_256 url: https://my_secure_domain.com/webhook created_time: 2023-02-24 23:20:28+00:00 events: - '*' last_modified_time: 2023-02-24 23:20:28+00:00 name: my_webhook_name token: my_webhook_token schema: $ref: '#/components/schemas/webhook_response_model' description: Success '400': content: {} description: User input error/Bad request '409': content: {} description: Request already processed with a different payload '500': content: {} description: Server error summary: Create webhook tags: - Webhooks /webhooks/customheaders/{token}: put: description: Adds or updates a webhook's custom HTTP headers. operationId: putWebhooksCustomHeadersToken parameters: - description: Unique identifier of the webhook. explode: false in: path name: token required: true schema: type: string style: simple requestBody: content: application/json: example: custom_header: my_header_name_1: my_value_1 my_header_name_2: my_value_2 my_header_name_3: my_value_3 schema: $ref: '#/components/schemas/WebhookUpdateCustomHeaderRequest' required: false responses: '200': content: application/json: example: active: true config: basic_auth_password: m**********d basic_auth_username: m**********e custom_header: my_header_name_1: my_value_1 my_header_name_2: my_value_2 my_header_name_3: my_value_3 secret: m**********t signature_algorithm: HMAC_SHA_256 url: https://my_secure_domain.com/webhook created_time: 2023-02-06 08:12:32+00:00 events: - transaction.* last_modified_time: 2023-02-26 22:07:23+00:00 name: my_webhook_name token: my_webhook_01 schema: $ref: '#/components/schemas/webhook_response_model' description: Success '400': content: {} description: User input error/Bad request '404': content: {} description: Resource not found '500': content: {} description: Server error summary: Update webhook custom headers tags: - Webhooks /webhooks/{token}: get: description: '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 you can access these values as needed, update them on your endpoint, store them securely, and then <>.' operationId: getWebhooksToken parameters: - description: Unique identifier of the webhook. explode: false in: path name: token required: true schema: type: string style: simple responses: '200': content: application/json: schema: $ref: '#/components/schemas/webhook_response_model' description: Success '404': content: {} description: Resource not found '500': content: {} description: Server error summary: Retrieve webhook tags: - Webhooks put: description: '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 <> guide.' operationId: putWebhooksToken parameters: - description: Unique identifier of the webhook. explode: false in: path name: token required: true schema: type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/webhook_base_model' required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/webhook_response_model' description: Success '400': content: {} description: User input error/Bad request '404': content: {} description: Resource not found '500': content: {} description: Server error summary: Update webhook tags: - Webhooks /webhooks/{token}/ping: post: description: "Pings your webhook endpoint.\n\nSend a ping request to your webhook endpoint to validate credentials and connectivity.\nYour webhook endpoint must be configured to respond.\n\n=== Configuring your webhook endpoint\n\nWhen the Marqeta platform receives the ping request, it sends a `POST` request containing the following body to the URL of your webhook endpoint:\n\n[#ping-webhook-sample]\n[source,json]\n----\n{\n \"pings\": [\n {\n \"token\": \"marqeta\",\n \"payload\": \"healthcheck\"\n }\n ]\n}\n----\n\nTo indicate that it is functioning properly, your webhook endpoint must respond with a status code of `200` (see <> for a code example that identifies a ping request).\nThe response can optionally include a link:http://www.json.org/[JSON, window=\"_blank\"]-formatted body, for example:\n\n[#ping-webhook-sample-2]\n[source,json]\n----\n{\"my_endpoint_status\": \"alive\"}\n----\n\nThe Marqeta platform then responds to its requestor by echoing, as-is, the response code and body received from your webhook endpoint.\n\n=== Using the ping facility\n\nTo 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.\nInclude an empty, link:http://www.json.org/[JSON, window=\"_blank\"]-formatted body in the request, that is:\n\n[#ping-webhook-sample-3]\n[source,json]\n----\n{}\n----\n\nThe following chain of actions occurs during the successful execution of a ping operation:\n\n. The Marqeta platform receives the ping request (`POST` to `/webhooks/{token}/ping`).\n. The Marqeta platform sends a request to your webhook endpoint.\n. Your webhook endpoint responds with a status code of \"200\" and an optional body.\n. The Marqeta platform responds to its requestor by echoing, as-is, the response code and body it received from your webhook endpoint.\n\n[NOTE]\nIf 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):\n\n[#ping-webhook-sample-4]\n[source,json]\n----\n{\n \"error_message\": \"Webhook operation failed \" + ,\n \"error_code\": \"422600\"\n}\n----\n\nFailed pings are not automatically retried." operationId: postWebhooksTokenPing parameters: - description: Unique identifier of the webhook. explode: false in: path name: token required: true schema: type: string style: simple responses: '200': content: application/json: example: pings: - my_endpoint_status: alive schema: $ref: '#/components/schemas/webhook_ping_model' description: Success '400': content: {} description: User input error/Bad request '404': content: {} description: Resource not found '500': content: {} description: Server error summary: Ping webhook tags: - Webhooks /webhooks/{token}/{event_type}/{event_token}: post: description: '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.' operationId: postWebhooksTokenEventtypeEventtoken parameters: - description: Unique identifier of the webhook. explode: false in: path name: token required: true schema: type: string style: simple - description: Specifies the type of event you want to resend. explode: false in: path name: event_type required: true schema: enum: - chargebacktransition - digitalwallettokentransition - cardtransition - usertransition - businesstransition - transaction - threedstransition type: string style: simple - description: Unique identifier of the event for which you want to resend a notification. explode: false in: path name: event_token required: true schema: type: string style: simple responses: '200': content: {} description: Success '400': content: {} description: User input error/Bad request '404': content: {} description: Resource not found '500': content: {} description: Server error summary: Resend event notification tags: - Webhooks components: schemas: echo_ping_request: properties: payload: description: Payload of the ping request. type: string token: description: Unique identifier of the ping request. type: string type: object webhook_config_request_model: description: Contains the configuration information for the webhook. properties: basic_auth_password: description: Password for accessing your webhook endpoint. maxLength: 50 minLength: 20 type: string basic_auth_username: description: Username for accessing your webhook endpoint. maxLength: 50 minLength: 1 type: string custom_header: additionalProperties: type: string description: Custom headers to be passed along with the request. type: object secret: description: 'Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256 depending on value in `signature_algorithm`. 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 <>.' maxLength: 50 minLength: 20 type: string signature_algorithm: description: 'The 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 <>.' maxLength: 20 minLength: 1 type: string url: description: URL of your webhook endpoint. maxLength: 255 minLength: 1 type: string use_mtls: default: false description: '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.' type: boolean required: - basic_auth_password - basic_auth_username - url type: object webhook_response_model: properties: active: default: true description: 'Indicates whether the webhook is active. This field is returned if you included it in your webhook.' type: boolean config: $ref: '#/components/schemas/webhook_config_response_model' created_time: description: Date and time when the webhook event was created, in UTC. format: date-time type: string events: description: '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.*`.' items: type: string type: array last_modified_time: description: Date and time when the associated object was last modified, in UTC. format: date-time type: string name: description: Descriptive name of the webhook. maxLength: 64 minLength: 1 type: string token: description: Unique identifier of the webhook. maxLength: 36 minLength: 1 type: string required: - config - events - name type: object webhook_base_model: properties: active: default: true description: Indicates whether the webhook is active. type: boolean config: $ref: '#/components/schemas/webhook_config_request_model' events: description: '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.*`.' items: type: string type: array name: description: Descriptive name of the webhook. maxLength: 64 minLength: 1 type: string required: - config - events - name type: object webhook_request_model: properties: active: default: true description: Indicates whether the webhook is active. type: boolean config: $ref: '#/components/schemas/webhook_config_request_model' events: description: '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.*`.' items: type: string type: array name: description: Descriptive name of the webhook. maxLength: 64 minLength: 1 type: string token: description: Unique identifier of the webhook. maxLength: 36 minLength: 1 type: string required: - config - events - name type: object WebhookUpdateCustomHeaderRequest: properties: custom_header: additionalProperties: type: string description: '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.' type: object type: object webhook_ping_model: properties: pings: description: Array of ping requests to your webhook endpoint. items: $ref: '#/components/schemas/echo_ping_request' type: array required: - pings type: object webhook_config_response_model: description: Contains the configuration information for the webhook. properties: basic_auth_password: description: Password for accessing your webhook endpoint. maxLength: 12 minLength: 12 type: string basic_auth_username: description: Username for accessing your webhook endpoint. maxLength: 12 minLength: 12 type: string custom_header: additionalProperties: type: string description: Custom headers to be passed along with the request. type: object secret: description: 'Randomly chosen string used for implementing HMAC-SHA1 or HMAC-SHA256 depending on value in signature_algorithm. 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 <>.' maxLength: 12 minLength: 12 type: string signature_algorithm: description: 'The 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 <>.' maxLength: 20 minLength: 1 type: string url: description: URL of your webhook endpoint. maxLength: 255 minLength: 1 type: string use_mtls: default: false description: '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.' type: boolean required: - basic_auth_password - basic_auth_username - url type: object WebhookResponseModelListResponse: properties: count: description: 'Number of resources to retrieve. This field is returned if there are resources in your returned array.' format: int32 type: integer data: description: 'Array of webhooks resources. Resources are returned as appropriate to your query.' items: $ref: '#/components/schemas/webhook_response_model' type: array end_index: description: 'Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array.' format: int32 type: integer is_more: default: false description: '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.' type: boolean start_index: description: 'Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array.' format: int32 type: integer type: object securitySchemes: mqAppAndAccessToken: scheme: basic type: http