DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

15 minute read

October 2, 2019

Webhooks Management

A webhook is a messaging mechanism that enables you to receive notification of events as they occur. The Marqeta platform sends such event notifications to a webhook endpoint, an endpoint hosted in your environment that you have configured to receive and process event notifications. See the About Webhooks developer guide for more information.

The Marqeta API allows you to create a webhook object to represent your webhook endpoint within the Marqeta Platform. You configure the webhook object with the URL of your webhook endpoint and with a set credentials for accessing that endpoint. You also configure it to send notifications for specific types of events (you can configure it to send all types or any subset of types). If you would like to set up multiple webhook endpoints and route different types of event notifications to each, you can do so by creating multiple webhook objects and configuring each to send a specific type of event notification to a specific endpoint.

The Marqeta API additionally provides webhook ping and resend facilities. The ping facility lets you validate webhook credentials, connectivity, and aliveness of your webhook endpoint. The resend facility enables you to resend any specific event notification.

Note
Webhook configurations created by this endpoint are functional only in a production environment. If you want to test webhooks in the sandbox environment, configure a webhook object within your simulated transaction. For more information, see Simulating Transactions.

Create webhook
Copy section link

Action: POST
Endpoint: /webhooks

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

Body field details (request)
Copy section link

Fields Description

token

string, optional

Unique identifier of the webhook.

If you do not include a token, the system automatically generates one. This token is necessary for use in other API calls. It is recommended that, rather than let the system, you create a simple, easy-to-remember string. This value cannot be updated.

Allowable Values: 36 char max

name

string, required

Descriptive name of the webhook.

Allowable Values: 64 char max

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.

events

array of strings, required

Specifies the types of events for which notifications are sent.

Allowable Values: For a comprehensive list of events, see Event Types.

The config object (request)
Copy section link

Fields Description

url

string, required

URL of your webhook endpoint.

Allowable Values:

  • 255 char max

  • Must be HTTPS

  • Empty string not allowed

secret

string, optional

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.

Allowable Values:

  • 20-50 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

basic_auth_username

string, required

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string, required

Password for accessing your webhook endpoint.

Allowable Values:

  • 20-100 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

custom_header

object, optional

Contains information about custom headers for additional security beyond the required Basic Authentication.

Allowable Values:

See The config.custom_header object (request).

The config.custom_header object (request)
Copy section link

Fields Description

my_header_name_1
my_header_name_2
my_header_name_3

(500 char max per name)

Additional security information included in the HTTP header, along with Basic Authentication, for webhook notifications. The Marqeta customer defines the name and value of up to three fields, for example:

"custom_header": {
  "my_header_name_1": "my_value_1",
  "my_header_name_2": "my_value_2"
  "my_header_name_3": "my_value_3"
}

Is this helpful?

Allowable Values:

500 char max

Body field details (response)
Copy section link

Fields Description

token

string, optional

Unique identifier of the webhook.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values: 36 char max

name

string, required

Descriptive name of the webhook.

Allowable Values: 64 char max

active

boolean, optional

Indicates whether the webhook is active.

Allowable Values: true, false

config

object, required

Contains the configuration information for the webhook.

events

array of strings, required

Specifies the types of events for which notifications are sent.

Allowable Values: For a comprehensive list of events, see Event Types.

created_time

datetime, optional

Time the webhook event was created.

last_modified_time

datetime, optional

Time the associated object was last modified.

The config object (response)
Copy section link

Fields Description

url

string, required

URL of your webhook endpoint.

Allowable Values:

  • 255 char max

  • Must be HTTPS

  • Empty string not allowed

secret

string, optional

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.

Allowable Values:

  • 20-50 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

basic_auth_username

string, required

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string, required

Password for accessing your webhook endpoint.

Allowable Values:

  • 20-100 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

custom_header

object, optional

Contains information about custom headers for additional security beyond the required Basic Authentication.

Allowable Values:

See The config.custom_header object (response).

The config.custom_header object (response)
Copy section link

Fields Description

my_header_name_1
my_header_name_2
my_header_name_3

Additional security information defined by the Marqeta customer.

Allowable Values:

500 char max

Sample request body
Copy section link

{
  "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"
    "custom_header": {
      "my_header_name_1": "my_value_1",
      "my_header_name_2": "my_value_2"
    }
  },
  "name": "My_Webhook_Name"
}

Is this helpful?

Sample response body
Copy section link

{
  "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"
    "custom_header": {
      "my_header_name_1": "my_value_1",
      "my_header_name_2": "my_value_2"
    }
  },
  "events": [
    "*"
  ],
  "token": "my_webhook_token",
  "created_time": "2016-08-24T23:20:28Z",
  "last_modified_time": "2016-08-24T23:20:28Z"
}

Is this helpful?

Retrieve webhook
Copy section link

Action: GET
Endpoint: /webhooks/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a specific webhook.

URL path parameters (request)
Copy section link

Fields Description

token

string, required

Identifies the webhook to retrieve.

Allowable Values:

Existing webhook token.

Send a GET request to /webhooks to retrieve webhook tokens.

Body field details (response)
Copy section link

Fields Description

token

string, required

Identifies the webhook to retrieve.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

Existing webhook token.

name

string, required

Name of the webhook.

Allowable Values:

64 char max

active

boolean, optional

Indicates whether the webhook is active.

Allowable Values:

true, false

config

object, required

Contains the configuration information for the webhook.

Allowable Values:

events

array of strings, required

Specifies the types of events for which notifications are sent.

Allowable Values:

For a comprehensive list of events, see Event Types.

created_time

datetime, optional

Time when the webhook event was created.

Allowable Values:

last_modified_time

datetime, optional

Time when the associated object was last modified.

Allowable Values:

Sample response body
Copy section link

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

Is this helpful?

Update webhook
Copy section link

Action: PUT
Endpoint: /webhooks/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to update a webhook.

URL path parameters (request)
Copy section link

Fields Description

token

string, required

Identifies the webhook to update.

Allowable Values:

Existing webhook token. Send a GET request to /webhooks to retrieve webhook tokens.

Body field details (request)
Copy section link

Fields Description

name

string, required

Descriptive name of the webhook.

Allowable Values: 64 char max

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.

events

array of strings, required

Specifies the types of events for which notifications are sent.

Allowable Values: For a comprehensive list of events, see Event Types.

The config object (request)
Copy section link

Fields Description

url

string, required

URL of your webhook endpoint.

Allowable Values:

  • 255 char max

  • Must be HTTPS

  • Empty string not allowed

secret

string, optional

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.

Allowable Values:

  • 20-50 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

basic_auth_username

string, required

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string, required

Password for accessing your webhook endpoint.

Allowable Values:

  • 20-100 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

custom_header

object, optional

Contains information about custom headers for additional security beyond the required Basic Authentication.

Allowable Values:

See The config.custom_header object (request).

Body field details (response)
Copy section link

Fields Description

token

string, optional

Unique identifier of the webhook.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values: 36 char max

name

string, required

Descriptive name of the webhook.

Allowable Values: 64 char max

active

boolean, optional

Indicates whether the webhook is active.

Allowable Values: true, false

config

object, required

Contains the configuration information for the webhook.

events

array of strings, required

Specifies the types of events for which notifications are sent.

Allowable Values: For a comprehensive list of events, see Event Types.

created_time

datetime, optional

Time when the webhook event was created.

last_modified_time

datetime, optional

Time when the associated object was last modified.

The config object (response)
Copy section link

Fields Description

url

string, required

URL of your webhook endpoint.

Allowable Values:

  • 255 char max

  • Must be HTTPS

  • Empty string not allowed

secret

string, optional

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.

Allowable Values:

  • 20-50 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

basic_auth_username

string, required

Username for accessing your webhook endpoint.

Allowable Values:

50 char max

basic_auth_password

string, required

Password for accessing your webhook endpoint.

Allowable Values:

  • 20-100 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

custom_header

object, optional

Contains information about custom headers for additional security beyond the required Basic Authentication.

Allowable Values:

See The config.custom_header object (response).

Sample request body
Copy section link

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

Is this helpful?

Sample response body
Copy section link

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

Is this helpful?

List webhooks
Copy section link

Action: GET
Endpoint: /webhooks

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to return an array of all webhooks.

This endpoint supports field filtering, sorting, and pagination.

Sample response body
Copy section link

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

Is this helpful?

Ping webhook
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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 webhook 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
Copy section link

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

Is this helpful?

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

Is this helpful?

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
Copy section link

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:

{}

Is this helpful?

The following chain of actions occurs during 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"
}

Is this helpful?

Failed pings are not automatically retried.

Sample request body
Copy section link

{}

Is this helpful?

Sample response body
Copy section link

{"my_endpoint_status": "alive"}

Is this helpful?

Resend event notification
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Copy section link

Fields Description

token

string, required

The token identifying the webhook object that is configured to send event notifications to your webhook endpoint.

Allowable Values:

Existing webhook token.

Send a GET request to /webhooks to retrieve webhook tokens.

event_type

string, required

Specifies the type of event you want to resend.

Allowable Values:

usertransition, businesstransition, cardtransition, transaction, digitalwallettokentransition, chargebacktransition, commandomodetransition, casetransition

event_token

string, required

The token identifying the event for which you want to resend a notification.

Allowable Values:

Existing event token.

  • Send a GET request to /usertransitions/user/{token} to retrieve transition tokens related to a particular user.

  • Send a GET request to /businesstransitions/business/{token} to retrieve transition tokens related to a particular business.

  • Send a GET request to /cardtransitions/card/{card_token} to retrieve transition tokens related to a particular card.

  • Send a GET request to /transactions to retrieve transaction tokens.

  • Send a GET request to /digitalwallettokentransitions/digitalwallettoken/{token} to retrieve transition tokens related to a particular digital wallet token.

  • Send a GET request to /chargebacks/{chargeback_token}/transitions to retrieve chargeback transition tokens related to a particular chargeback.

  • Send a GET request to /commandomodes/{commandomode_token}/transitions to retrieve Commando Mode transition tokens related to a particular Commando Mode control set.

  • Send a GET request to /cases/{token}/transitions to retrieve case transition tokens related to a particular case.

Sample response bodies
Copy section link

The following sample response body shows a successful resend of an event notification.

{
  "transactions": [
    {
     "type": "authorization",
     "state": "PENDING",
     "token": "90d143e4-1051-46ab-a9ce-2a931d990e95",
     "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
     "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
     "card_token": "a039902f-2fb9-468b-ac23-fce2be690e37",
     "gpa": {
         "currency_code": "USD",
         "ledger_balance": 20,
         "available_balance": 0,
         "credit_balance": 0,
         "pending_credits": 0,
         "impacted_amount": -10,
         "balances": {
             "USD": {
                 "currency_code": "USD",
                 "ledger_balance": 20,
                 "available_balance": 0,
                 "credit_balance": 0,
                 "pending_credits": 0,
                 "impacted_amount": -10
             }
         }
     },
     "gpa_order": {
         "token": "15127077-fde3-4442-8304-c73daff9ace0",
         "amount": 10,
         "created_time": "2018-08-21T18:17:13Z",
         "last_modified_time": "2018-08-21T18:17:13Z",
         "transaction_token": "2c4adb00-a07a-4424-9470-cc4dcbc3c04f",
         "state": "PENDING",
         "response": {
             "code": "0000",
             "memo": "Approved or completed successfully"
         },
         "funding": {
             "amount": 10,
             "source": {
                 "type": "program",
                 "token": "**********b4c2",
                 "active": true,
                 "name": "PFS for simulating transactions",
                 "is_default_account": false,
                 "created_time": "2018-07-10T00:09:35Z",
                 "last_modified_time": "2018-07-10T00:09:35Z"
             }
         },
         "funding_source_token": "**********b4c2",
         "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
         "currency_code": "USD"
     },
     "duration": 159,
     "created_time": "2018-08-21T18:17:13Z",
     "user_transaction_time": "2018-08-21T18:17:13Z",
     "settlement_date": "2018-08-21T00:00:00Z",
     "request_amount": 10,
     "amount": 10,
     "issuer_interchange_amount": 0,
     "currency_code": "USD",
     "approval_code": "013419",
     "response": {
         "code": "0000",
         "memo": "Approved or completed successfully"
     },
     "network": "VISA",
     "subnetwork": "VISANET",
     "acquirer_fee_amount": 0,
     "acquirer": {
         "institution_country": "840",
         "institution_id_code": "375321467",
         "retrieval_reference_number": "526051868288",
         "system_trace_audit_number": "676127"
     },
     "user": {
         "metadata": {}
     },
     "card": {
         "metadata": {}
     },
     "card_security_code_verification": {
         "type": "CVV1",
         "response": {
             "code": "0000",
             "memo": "Card security code match"
         }
     },
     "fraud": {
         "network": {
             "transaction_risk_score": 86,
             "account_risk_score": 2
         }
     },
     "card_acceptor": {
         "mid": "000000000011111",
         "mcc": "6411",
         "name": "Chicken Tooth Music",
         "street_address": "111 Main St",
         "city": "Berkeley",
         "country_code": "USA"
     },
     "pos": {
         "pan_entry_mode": "MAG_STRIPE",
         "pin_entry_mode": "TRUE",
         "terminal_id": "TR100000",
         "terminal_attendance": "ATTENDED",
         "card_holder_presence": false,
         "card_presence": false,
         "partial_approval_capable": false,
         "purchase_amount_only": false,
         "is_recurring": false
     },
     "transaction_metadata": {
         "payment_channel": "OTHER"
     }
   }
  ]
}

Is this helpful?

An incorrectly entered card number with a BIN prefix coincidentally associated with your program can return failure codes such as those shown in the following response:

{
   "transactions": [
       {
           "type": "authorization",
           "state": "DECLINED",
           "identifier": "677",
           "token": "7cf6db10-5d3a-43f8-aa56-ab21ee23f254",
           "duration": 27,
           "created_time": "2019-06-03T08:11:22Z",
           "user_transaction_time": "2019-06-03T08:11:22Z",
           "settlement_date": "2019-06-03T00:00:00Z",
           "request_amount": 0.01,
           "amount": 0.01,
           "currency_conversion": {
               "network": {
                   "original_amount": 0.02,
                   "conversion_rate": 0.5000000,
                   "original_currency_code": "124"
               }
           },
           "currency_code": "USD",
           "response": {
               "code": "1011",
               "memo": "Card not found"
           },
           "network": "VISA",
           "subnetwork": "VISANET",
           "acquirer_fee_amount": 0,
           "acquirer": {
               "institution_country": "124",
               "institution_id_code": "406449",
               "retrieval_reference_number": "915408301475",
               "system_trace_audit_number": "301475"
           },
           "fraud": {
               "network": {
                   "transaction_risk_score": 23
               }
           },
           "issuer_received_time": "2019-06-03T08:11:22.215Z",
           "issuer_payment_node": "baa462ac7d5e36143bdd21df49d95af8",
           "card_acceptor": {
               "mid": "000000000011111",
               "mcc": "6411",
               "name": "Chicken Tooth Music",
               "city": "Berkeley",
               "country_code": "USA"
           },
           "pos": {
               "pan_entry_mode": "MANUAL",
               "pin_entry_mode": "FALSE",
               "terminal_id": "TR100000",
               "terminal_attendance": "UNSPECIFIED",
               "card_holder_presence": false,
               "card_presence": false,
               "card_data_input_capability": "NO_TERMINAL",
               "partial_approval_capable": false,
               "purchase_amount_only": false,
               "is_recurring": false
           },
           "transaction_metadata": {
               "payment_channel": "ECOMMERCE"
           }
       }
   ]
}

Is this helpful?

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.