Create webhook

Action: POST
Endpoint: /webhooks

Use this endpoint to create a webhook. A webhook is a configuration object that let's you configure the types of event notifications that are sent, the location to where they are sent (the URL of your webhook endpoint), and credentials for accessing the webhook endpoint.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the webhook.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
36 char max
name string Yes Descriptive name of the webhook. 64 char max
active boolean No Indicates whether the webhook is active. true | false

Default: true
config object Yes Contains the configuration information for the webhook.
events array of strings Yes Specifies the types of events for which notifications are sent.

This field contains a comma delimited array of strings. Each string can specify one of the following:
  • a single event type (for example, "transaction.gpa.debit")
  • a group of event types (for example, "transaction.*" or "cardtransition.*")
  • all event types ("*")
.
*
usertransition.*
usertransition.unverified
usertransition.limited
usertransition.active
usertransition.suspended
usertransition.closed
businesstransition.*
businesstransition.unverified
businesstransition.limited
businesstransition.active
businesstransition.suspended
businesstransition.closed
cardtransition.*
cardtransition.fulfillment.issued
cardtransition.state.activated
cardtransition.state.suspended
cardtransition.state.reinstated
cardtransition.state.terminated
cardtransition.fulfillment.ordered
cardtransition.fulfillment.reordered
cardtransition.fulfillment.rejected
cardtransition.fulfillment.shipped
cardtransition.fulfillment.delivered
cardtransition.fulfillment.digitally_presented
transaction.*
transaction.authorization
transaction.authorization.advice
transaction.authorization.clearing
transaction.authorization.reversal
transaction.authorization.reversal.issuerexpiration
transaction.fee.charge
transaction.fee.charge.pending
transaction.fee.charge.reversal
transaction.funds.expire
transaction.gpa.credit
transaction.gpa.credit.authorization
transaction.gpa.credit.networkload
transaction.gpa.credit.pending
transaction.gpa.credit.pending.reversal
transaction.gpa.credit.reversal
transaction.gpa.debit
transaction.gpa.debit.networkload
transaction.msa.credit
transaction.msa.credit.pending
transaction.msa.credit.pending.reversal
transaction.msa.credit.reversal
transaction.msa.debit
transaction.pindebit
transaction.pindebit.atm.withdrawal
transaction.pindebit.balanceinquiry
transaction.pindebit.cashback
transaction.pindebit.refund.reversal
transaction.refund
transaction.reward.earn
transaction.unknown
transaction.token.activation-request
digitalwallettokentransition.*
digitalwallettokentransition.fulfillment.requested
digitalwallettokentransition.state.request_declined
digitalwallettokentransition.state.activated
digitalwallettokentransition.state.suspended
digitalwallettokentransition.state.reinstated
digitalwallettokentransition.state.terminated
digitalwallettokentransition.card.swap
chargebacktransition.*
chargebacktransition.initiated
chargebacktransition.representment
chargebacktransition.prearbitration
chargebacktransition.arbitration
chargebacktransition.case.won
chargebacktransition.case.lost
chargebacktransition.network.rejected
chargebacktransition.written.off.issuer
chargebacktransition.written.off.program
directdeposit.credit
directdeposit.debit
directdeposit.credit.pending
directdeposit.debit.pending
directdeposit.credit.reversal
directdeposit.debit.reversal
directdeposit.credit.pending.reversal
directdeposit.debit.pending.reversal
directdeposit.credit.reject
directdeposit.debit.reject
commandomodetransition.enabled
commandomodetransition.disabled

The config object

Name Type Required? Description Allowable Values
url string Yes URL of your webhook endpoint. 255 char max.

Must be HTTPS.

Empty string not allowed.
secret string No A randomly chosen string used for implementing HMAC-SHA1.

HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification.
  • 20-50 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?
basic_auth_username string Yes Username for accessing your webhook endpoint. 50 char max
basic_auth_password string Yes Password for accessing your webhook endpoint.
  • 20-50 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?

Sample request body

{
"token": "my_webhook_token",
"active": true,
"events": [
"*"
],
"config": {
"url": "https://my_secure_domain.com/webhook",
"secret": "My_20-character-min_secret",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password"
},
"name": "My_Webhook_Name"
}

Sample response body

{
"name": "My_Webhook_Name",
"active": true,
"config": {
"url": "https://my_secure_domain.com/webhook",
"secret": "My_20-character-min_secret",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password"
},
"events": [
"*"
],
"token": "my_webhook_token",
"created_time": "2016-08-24T23:20:28Z",
"last_modified_time": "2016-08-24T23:20:28Z"
}


Retrieve webhook

Action: GET
Endpoint: /webhooks/{token}

Use this endpoint to retrieve a specific webhook.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the webhook to retrieve. Existing webhook token.

Issue a GET to /webhooks to retrieve webhook tokens.

Sample response body

{
"name": "My_Webhook_Name",
"active": true,
"config": {
"url": "https://my_secure_domain.com/webhook",
"secret": "My_20-character-min_secret",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password"
},
"events": [
"*"
],
"token": "my_webhook_token",
"created_time": "2016-08-24T23:20:28Z",
"last_modified_time": "2016-08-24T23:20:28Z"
}


Update webhook

Action: PUT
Endpoint: /webhooks/{token}

Use this endpoint to update a webhook.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the webhook to update. Existing webhook token. Issue a GET to /webhooks to retrieve webhook tokens.

Body field details

Name Type Required? Description Allowable Values
name string Yes Descriptive name of the webhook. 64 char max
active boolean No Indicates whether the webhook is active. true | false

Default: true
config object Yes Contains the configuration information for the webhook.
events array of strings Yes Specifies the types of events for which notifications are sent.

This field contains a comma delimited array of strings. Each string can specify one of the following:
  • a single event type (for example, "transaction.gpa.debit")
  • a group of event types (for example, "transaction.*" or "cardtransition.*")
  • all event types ("*")
.
*
usertransition.*
usertransition.unverified
usertransition.limited
usertransition.active
usertransition.suspended
usertransition.closed
businesstransition.*
businesstransition.unverified
businesstransition.limited
businesstransition.active
businesstransition.suspended
businesstransition.closed
cardtransition.*
cardtransition.fulfillment.issued
cardtransition.state.activated
cardtransition.state.suspended
cardtransition.state.reinstated
cardtransition.state.terminated
cardtransition.fulfillment.ordered
cardtransition.fulfillment.reordered
cardtransition.fulfillment.rejected
cardtransition.fulfillment.shipped
cardtransition.fulfillment.delivered
cardtransition.fulfillment.digitally_presented
transaction.*
transaction.authorization
transaction.authorization.advice
transaction.authorization.clearing
transaction.authorization.reversal
transaction.authorization.reversal.issuerexpiration
transaction.fee.charge
transaction.fee.charge.pending
transaction.fee.charge.reversal
transaction.funds.expire
transaction.gpa.credit
transaction.gpa.credit.authorization
transaction.gpa.credit.networkload
transaction.gpa.credit.pending
transaction.gpa.credit.pending.reversal
transaction.gpa.credit.reversal
transaction.gpa.debit
transaction.gpa.debit.networkload
transaction.msa.credit
transaction.msa.credit.pending
transaction.msa.credit.pending.reversal
transaction.msa.credit.reversal
transaction.msa.debit
transaction.pindebit
transaction.pindebit.atm.withdrawal
transaction.pindebit.balanceinquiry
transaction.pindebit.cashback
transaction.pindebit.refund.reversal
transaction.refund
transaction.reward.earn
transaction.unknown
transaction.token.activation-request
digitalwallettokentransition.*
digitalwallettokentransition.fulfillment.requested
digitalwallettokentransition.state.request_declined
digitalwallettokentransition.state.activated
digitalwallettokentransition.state.suspended
digitalwallettokentransition.state.reinstated
digitalwallettokentransition.state.terminated
digitalwallettokentransition.card.swap
chargebacktransition.*
chargebacktransition.initiated
chargebacktransition.representment
chargebacktransition.prearbitration
chargebacktransition.arbitration
chargebacktransition.case.won
chargebacktransition.case.lost
chargebacktransition.network.rejected
chargebacktransition.written.off.issuer
chargebacktransition.written.off.program
directdeposit.credit
directdeposit.debit
directdeposit.credit.pending
directdeposit.debit.pending
directdeposit.credit.reversal
directdeposit.debit.reversal
directdeposit.credit.pending.reversal
directdeposit.debit.pending.reversal
directdeposit.credit.reject
directdeposit.debit.reject
commandomodetransition.enabled
commandomodetransition.disabled

The config object

Name Type Required? Description Allowable Values
url string Yes URL of your webhook endpoint. 255 char max.

Must be HTTPS.

Empty string not allowed.
secret string No A randomly chosen string used for implementing HMAC-SHA1.

HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your webhook endpoint verify the message signature. For information about implementing this functionality, see Signature Verification.
  • 20-50 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?
basic_auth_username string Yes Username for accessing your webhook endpoint. 50 char max
basic_auth_password string Yes Password for accessing your webhook endpoint.
  • 20-50 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?

Sample request body

{
"events": [
"transaction.*"
]
}

Sample response body

{
"name": "My_Webhook_Name",
"active": true,
"config": {
"url": "https://my_secure_domain.com/webhook",
"secret": "My_20-character-min_secret",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password"
},
"events": [
"transaction.*"
],
"token": "my_webhook_token",
"created_time": "2016-08-24T23:20:28Z",
"last_modified_time": "2016-08-24T23:20:28Z"
}


List webhooks

Action: GET
Endpoint: /webhooks

Use this endpoint to return an array of all webhooks.

This endpoint supports field filtering, sorting, and pagination.

Sample response body

{
"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": "My_20-character-min_secret",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password"
},
"events": [
"*"
],
"token": "my_webhook_token",
"created_time": "2016-08-24T23:20:28Z",
"last_modified_time": "2016-08-24T23:20:28Z"
}
]
}


Ping webhook

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

Use this endpoint to ping a webhook endpoint and echo its response.

You receive event notifications by way of a specially configured endpoint hosted in your environment (the webhook endpoint). This ping facility lets you send a ping request to your wehbook endpoint from the Marqeta platform in order to validate credentials and connectivity and check that the endpoint is responsive. Your webhook endpoint must be configured to respond to the ping request appropriately in order for the ping facility to provide the appropriate information in its response.

Configuring your webhook endpoint

This subsection describes the ping request that your webhook endpoint should expect and its expected response.

When the Marqeta platform receives the ping request, it sends a POST request containing the following body to the URL of your webhook endpoint:

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

{"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 the webhook to ping. Include an empty, JSON-formatted body in the request, that is:

{}

The following chain of actions occurs duing a successful ping:

  1. The Marqeta platform receives the ping request (POST to /webhooks/{token}/ping).
  2. The Marqeta platform sends a request to your webhook endpoint.
  3. Your webhook endpoint responds with a status code of "200" and an optional body.
  4. The Marqeta platform responds to its requestor by echoing, "as is", the response code and body received from your webhook endpoint.

Note: If the customer-hosted endpoint fails to respond within 5 seconds, the Marqeta platform times out the request and responds with the following message body (where <optional message> is an optional message):

{
"error_message" : "Webhook operation failed " + <optional message>,
"error_code" : "422600"
}

Failed pings are not automatically retried.

Sample request body

{}

Sample response body

{"my_endpoint_status": "alive"}


Resend event notification

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

Use this endpoint to resend an event notification to your webhook endpoint. Note that although you send this request as a POST, all parameters are on the URL, and the body is empty. The event notification is resent to your webhook endpoint and also returned in the response to this request.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The token identifying the webhook object that is configured to send event notifications to your webhook endpoint. Existing webhook token.

Issue a GET to /webhooks to retrieve webhook tokens.
event_type string Yes Specifies the type of event you want to resend. usertransition | businesstransition | cardtransition | transaction | digitalwallettokentransition | chargebacktransition | commandomodetransition
event_token string Yes The token identifying the event for which you want to resend a notification. Existing event token.

Issue a GET to /usertransitions/user/{token} to retrieve transition tokens related to a particular user.
Issue a GET to /businesstransition/business/{token} to retrieve transition tokens related to a particular business.
Issue a GET to /cardtransitions/card/{card_token} to retrieve transition tokens related to a particular card.
Issue a GET to /transactions to retrieve transaction tokens.
Issue a GET to /digitalwallettokentransitions/digitalwallettoken/{token} to retrieve transition tokens related to a particular digital wallet token.
Issue a GET to /chargebacks/{chargeback_token}/transitions to retrieve chargeback transition tokens related to a particular chargeback.
Issue a GET to /commandomodes/{commandomode_token}/transitions to retrieve Commando Mode transition tokens related to a particular Commando Mode control set.

Sample response bodies

{
"cards": [
{
"token": "93b7c783-e9ec-46ce-9299-b9468c131772",
"state": "UNACTIVATED",
"reason": "New card",
"channel": "SYSTEM",
"validations": {
"user": {
"phone": false,
"ssn": false,
"birth_date": false
}
},
"type": "fulfillment.issued",
"pan": "123456______0014",
"expiration": "0820",
"card_token": "7ad9675d-8fab-47c2-9d3e-29dc78d911d9",
"user_token": "42abe318-a4ed-447e-99b9-78292e0fe121",
"fulfillment_status": "ISSUED",
"created_time": "2016-08-25T23:14:26Z",
"card_product_token": "102e3235-535c-4a30-9728-6bc4e4aadf2d",
"last_four": "0014",
"expiration_time": "2020-09-01T06:59:59.000Z",
"pin_is_set": false
}
]
}

{
"transactions": [
{
"type": "authorization",
"state": "PENDING",
"token": "191",
"user_token": "my_user_01",
"acting_user_token": "my_user_01",
"card_token": "my_user_01_card_03",
"duration": 116,
"created_time": "2017-05-12T18:21:29Z",
"user_transaction_time": "2017-05-12T18:21:29Z",
"settlement_date": "2017-05-12T00:00:00Z",
"request_amount": 10.0,
"amount": 10.0,
"issuer_interchange_amount": 0,
"currency_code": "USD",
"approval_code": "756895",
"response": {
"code": "0000",
"memo": "Approved or completed successfully"
},
"card_acceptor": {
"mid": "11111",
"mcc": "6411",
"name": "Chicken Tooth Music",
"address": "111 Main St",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"country": "USA"
},
"pos": {
"partial_approval_capable": "TRUE"
}
"gpa": {
"currency_code": "USD",
"ledger_balance": 2178.0,
"available_balance": 2158.0,
"credit_balance": 0.0,
"pending_credits": 0.0,
"impacted_amount": -10.0,
"balances": {
"USD": {
"currency_code": "USD",
"ledger_balance": 2178.0,
"available_balance": 2158.0,
"credit_balance": 0.0,
"pending_credits": 0.0,
"impacted_amount": -10.0
}
}
},
"network": "DISCOVER",
"acquirer_fee_amount": 0,
"user": {
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
}
]
}