Webhooks

Webhooks are user-defined HTTP callbacks from Burton to your server to notify you of events.

Configuring Webhooks

Creating webhook subscriptions is not yet available through the API. Contact your Integration Partner for assistance.

Once your webhook subscription is configured you will be provided a "webhook key" which you should store and keep secret. It is a shared secret between Burton and your webhook receiving endpoint used to validate notifications you receive. See the Verifying Received Webhooks section below for more details.

Receiving Webhooks

Create an endpoint on your server to receive webhooks by handling incoming HTTP POST requests. The webhook request will timeout in about a minute. Ideally the agent listening at this endpoint will only perform some light validation and then place the message into a queue or data store for later processing. The agent must respond with an HTTP 200 for the webhook to register the request as complete. No body is required for the response. The request content will be a JSON-encoded object which contains one or more events that you are subscribed to.

Assuming you decoded the JSON payload to a body variable the schema is:

body.webhook_id Unique webhook subscription id
body.timestamp The current date and time on the sending server
body.objects[] An array of event objects for events you have subscribed to

Assuming you loop through body.objects[], assigning each element to an event variable, the notification objects have the following schema:

event.type The object type.
- Possible values: merchant, entity, account, charge, distribution, distribution_item, message
event.events An array of strings listing one or more events that were triggered for the object.
- Possible values: create, update, delete, status
event.attempt_number Webhooks will retry sending to your endpoint until you return an HTTP 200 response code. attempt_number tells you how many times Burton has attempted to send the webhook callback for this object
event.timestamp Date and time when the event originally occurred
event.object_timestamp Date and time of the version of the object content contained in event.object
event.object Content of the object that triggered the event, or events. These objects use the following schemas:
- merchant: GetMerchant response
- entity: GetMerchantEntity response
- account: GetAccount response
- charge: A single items array object, in the GetCharges response
- distribution: A single items array object, in the GetDistribution response
- distribution_item: A single items array object, in the GetDistributionItems response
- message: GetMessage response

Sample payload:

{
    "webhook_id": "5e68278fab48f373c8337cbd",
    "timestamp": "2020-03-17T14:13:08.963Z",
    "objects": [
        {
            "type": "charge",
            "events": [
                "update",
                "status"
            ],
            "attempt_number": 1,
            "timestamp": "2020-03-10T23:49:58.000Z",
            "object_timestamp": "2020-03-10T23:50:12.000Z",
            "object": {
                "charge_id": "6e682751ab48f373d8237cd2",
                // ...the rest of a Charge object payload...
            }
        },
        {
            "type": "charge",
            "events": [
                "create"
            ],
            "attempt_number": 1,
            "timestamp": "2020-03-10T23:52:26.000Z",
            "object_timestamp": "2020-03-10T23:52:41.000Z",
            "object": {
                "charge_id": "6e682751ab48f578d8237ce3",
                // ...the rest of a Charge object payload...
            }
        }
    ]
}

Verifying Received Webhooks

All POST requests to your webhook endpoint will include a X-Content-Signature header that is an SHA256 hash of the notification.

Your webhook receiver should calculate the hash of the notification it receives and compare it to the value of the X-Content-Signature header to verify that it was sent by Burton.

Use the following process to calculate the hash:

The X-Content-Signature header is composed of 3 key pieces of information, separated by a colon (:)
- Calculated hash in base64. Referenced as hash in the samples below.
- Random salt in base64. Referenced as salt in the samples below.
- The number of iterations. Referenced as iterations in the samples below.
```
signature_parts = x_content_signature.split(':');
hash = signature_parts[0];
salt = signature_parts[1];
iterations = signature_parts[2];
```
Combine the POST body you received with your webhook key.
```
//Pseudo code
combined = body + webhook_key;
```
Generate the SHA256 hash of this combined string. Use the settings of signature[1] for the salt, signature[2] for the iterations, and 64 output bytes for the SHA256 hashing function.
```
new_hash = pbkdf2(combined, base64Decode(salt), iterations, 64, 'sha256');
```
Base64 encode the output of the SHA256 hashing function.
```
new_encoded_hash = base64Encode(new_hash);
```
Compare the hash you have generated to the value of the first section of the X-Content-Signature header. If they do not match then the message is not valid and not from Burton.
```
if (hash === new_encoded_hash) {
    //Valid message
} else {
    //Ignore invalid message
}
```

Webhook Bodies

Below are all webhook bodies that are not mentioned above.

Chargeback Webhook

{
  "webhook_id": "5e68278fab48f373c8337cbd",
  "timestamp": "2024-03-13T14:06:14.546Z",
  "objects": [
    {
      "type": "chargeback",
      "events": [
        "update"
      ],
      "attempt_number": 1,
      "timestamp": "2024-02-12T19:51:43.493Z",
      "event_timestamp": "2024-02-12T19:51:43.490Z",
      "object": {
        "charge_id": "65ca76ced713bc182beba0af",
        "chargeback_id": "65ca76ced713bc182beba0b0",
        "dispute_amount": 25,
        "response_date": "2024-02-26T19:51:42.556Z",
        "status_date": "2024-02-12T19:51:42.000Z",
        "network": "visa",
        "stage": "retrieval",
        "occurence_number": 0,
        "first_report_date": "2024-02-12T00:00:00.000Z",
        "effective_date": "2024-02-12T00:00:00.000Z",
        "transaction_date": "2024-02-11T19:51:42.000Z",
        "last_four": "1234",
        "account_id": "mt_065ca76cbd713bc182beba0a6ckR74GPGiQjxTB5u4soom",
        "account_name": "Long-Johns ACH",
        "entry_mode": "01",
        "entry_mode_description": "Manually Keyed",
        "acquirer_reference_number": "xxxxx",
        "chargeback_type": "41",
        "action_code": "CHGM",
        "chargeback_reports": [
            "string"
        ],
        "report_date": "2024-02-11T19:51:42.558Z",
        "transaction_status": "string",
        "merchant_id": "pa_065ca76cad713bc182beba0a1",
        "merchant_name": "Account# 5198437898",
        "transaction_amount": 100,
        "payer_name": "John Doe",
        "transaction_description": "test description",
        "invoice_number": "12345",
        "po_number": "67890",
        "chargeback_type_message": "Credit card chargeback of purchase",
        "adjustment_type_message": "CreditCard Retrieval Request",
        "action_required": false,
        "action_code_mesage": "Charge Merchant (debit) -- Financial",
        "adjustment_reason_code": "B-06257",
        "adjustment_reason_code_message": "Detailed reason for the adjustment",
        "dealer_merchant_id": "pr_065ca76cad713bc182beba0a1",
        "dealer_merchant_name": "Account# 5198437898"
      }
    }
  ]
}