Overview

Receive real time notifications of payments, subscriptions, and much more.

Webhooks enable you to receive notifications upon certain webstore events, for example when a new payment is made. We will send a HTTP request containing a JSON object to any configured endpoints that are subscribing to the respective event. Webhooks are a great way to integrate Tebex with your own website, forum or internal database.

How To Setup Webhooks Endpoints

1. Go to Developers > Webhooks > Endpoints.

2. Click Add Endpoint.

3. Enter the URL of your webhook endpoint.

4. Select the types of webhooks that you'd like to subscribe to.

5. Click Add.

After adding your endpoint, you will receive a warning to inform you that we haven't been able to validate endpoint. Please see the section below for further information about handling validation webhooks.

Handling Validation Webhooks

Webhooks will not be sent to an endpoint unless it has been validated first. This is to ensure we are not sending HTTP requests to URLs that are not expecting our webhooks.

The validation webhook that we send will look similar to the example below. To identify a validation webhook you can check the type property in the JSON body.

{
  "id": "2c116b11-1110-91e0-b266-b792c8da5f11",
  "type": "validation.webhook",
  "date": "2021-08-24T12:21:47+00:00",
  "subject": {}
}

Upon receiving a validation webhook you must respond with a 200 OK response containing a JSON object that has an id property representing the validation webhook's ID, please see the example response below.

{
  "id": "2c116b11-1110-91e0-b266-b792c8da5f11"
}

Once your endpoint is setup to successfully handle validation webhooks, please visit Developers > Webhooks > Endpoints and click the Validate button next to the endpoint to re-send the validation webhook.

Verifying Webhook Authenticity

IP Address

Webhooks from Tebex will only ever be sent from the two IP addresses listed below.

18.209.80.3 54.87.231.232

When building your webhook endpoint, we suggest that you check the IP address of the sender and throw a 404 Not Found error if the IP address isn't in the above list.

Signature

In addition to checking the IP address, we strongly advise that you verify the X-Signature header that we send with all requests.

The signature is generated by SHA256 hashing the JSON body and then building a SHA256 HMAC with the body hash as the data/content and your webhook secret as the key.

Your webhook secret is displayed on the Developers > Webhooks > Endpoints page. Please see our example code snippets below of how to generate the signature.

PHP

$json = file_get_contents('php://input');
$secret = "0d45982a10e3a072d0c1261c55dd9918";
$signature = hash_hmac('sha256', hash('sha256', $json), $secret);

Node.js (Express)

var bodyParser = require('body-parser');

var app = express();

app.use(bodyParser.json({
  verify: (req, res, buf) => {
    req.rawBody = buf
  }
}));

router.post('/webhook', function(req, res, next) {
  const secret = 'xxxxxxxxxxx';

  const bodyHash = crypto
      .createHash('sha256')
      .update(req.rawBody.toString(), 'utf-8')
      .digest('hex');
  const finalHash = crypto.createHmac('sha256', secret)
      .update(bodyHash)
      .digest('hex');
  console.log('finalHash', finalHash)

  // Compare hash...
});

If the signature that you generate doesn't match the X-Signature header, please disregard the webhook because it is not from Tebex.

Some frameworks such as Express (Node.js) automatically parse JSON request bodies which can result in a signature mismatch. Please ensure the signature is calculated using the raw request body and not a parsed version of the body.

Handling Webhooks

All of our webhooks are sent using the standardised format with the following properties:

id: This property represents the unique ID of the webhook. type: The type of webhook we are sending, for example payment.completed. date: This is the date that the webhook was generated. subject: The data within this property will differ depending on the type of webhook. To view the different subject formats please see the subject types below.

When handling a webhook, please ensure you respond with a 2XX status code (anywhere between 200-299). If your endpoint responds with any other status code we will automatically try to resend the webhook later-on.

After several attempts of retrying we will mark the webhook as failed and your endpoint may require validating again.

Webhook Types

• payment.completed

• payment.declined

• payment.refunded

• payment.dispute.opened

• payment.dispute.won

• payment.dispute.lost

• payment.dispute.closed

• recurring-payment.started

• recurring-payment.renewed

• recurring-payment.ended

• recurring-payment.cancellation.requested

• recurring-payment.cancellation.aborted

• validation.webhook

Webhook Subjects

Payment

{
  "transaction_id": "tbx-xxxxxxxx",
  "status": {
    ,
    "description": "Refund"
  },
  "payment_sequence": "oneoff",
  "created_at": "2021-08-19T13:03:30.000000Z",
  "price": {
    "amount": 13.2,
    "currency": "GBP"
  },
  "price_paid": {
    "amount": 13.2,
    "currency": "GBP"
  },
  "payment_method": {
    "name": "PayPal",
    "refundable": true
  },
  "fees" : {
    "tax" : {
      "amount" : 0,
      "currency" : "USD"
    },
    "gateway" : {
      "amount" : 0.73,
      "currency" : "USD"
    }
  },
  "customer": {
    "first_name": "Test",
    "last_name": "Test",
    "email": "[e-mail]",
    "ip": "1.2.3.4",
    "username": {
      "id": "1234",
      "username": "Test"
    },
    "marketing_consent": true,
    "country": "GB",
    "postal_code": "TE57 1NG"
  },
  "products": [
    {
      "id": 4,
      "name": "Example Package",
      "quantity": 1,
      "base_price": {
        "amount": 11,
        "currency": "GBP"
      },
      "paid_price": {
        "amount": 11,
        "currency": "GBP"
      },
      "variables": [
        {
          "identifier": "server",
          "option": "3"
        }
      ],
      "expires_at": null,
      "custom": null,
      "username": {
        "id": "1234",
        "username": "Test"
      }
    }
  ],
  "coupons": [],
  "gift_cards": [],
  "recurring_payment_reference": null,
  "decline_reason": {
    ,
    "message": "You entered incorrect card information. Please check your card details are correct and then try again."
  }
}

Useful Status IDs

ID	Status
1	Complete
2	Refund
3	Chargeback
18	Declined
19	Pending Checkout
21	Refund Pending

Decline Reasons

Code	Message
rejected	The payment method was declined by the customers payment method provider. We recommend asking the customer to contact their bank/provider to have this issue resolved.
fraud_card_issuer	The payment method was declined by the customers card issuer or their bank due to suspected fraud. We recommend asking the customer to contact their bank to have this issue resolved.
fraud_tebex	Tebex implements artificial intelligence to determine if a transaction is fraudulent. Based on the data we have collected, we have decided this transaction to be too risky to accept. Do not tell the customer that they have been blocked due to fraud.
incorrect_card_information	The customer has entered incorrect card details during the checkout process. Please advise the customer to try again with the correct details.
network_failure	There was a failure in the payment network. Please advise the customer to try again later.
insufficient_funds	The payment method was declined due to the customer having insufficient funds.
fraud_history	Tebex reviews the fraud history of customers as part of our fraud assessment. Based on the data we have collected, the fraud history of this customer makes this transaction too risky to accept. Do not tell the customer that they have been blocked due to fraud.

Recurring Payment

{
  "reference": "tbx-r-xxxxx",
  "created_at": "2021-08-23T11:33:51.000000Z",
  "next_payment_at": "2021-09-23T11:34:13.000000Z",
  "status": {
    ,
    "description": "Cancelled"
  },
  "initial_payment": ,
  "last_payment": ,
  "fail_count": 0,
  "price": {
    "amount": 20,
    "currency": "GBP"
  },
  "cancelled_at": "2021-08-24T14:46:05.000000Z",
  "cancel_reason": "Cancelled by webstore on request"
}

Useful Status IDs

ID	Status	Description	Active
2	Active	The recurring payment is active.
3	Overdue	We couldn't charge the customer for the renewal, but we will automatically retry tomorrow.
4	Expired	After multiple attempts, we couldn't renew the recurring payment.
5	Cancelled	The recurring payment has been cancelled as requested by the creator/customer.
7	Pending Downgrade	Only applies to recurring payments for packages in Tiered Categories: The customer has requested to downgrade their recurring payment to a lower priced package.

Testing Webhooks

Our webhook testing feature allows you to manually trigger webhooks from your control panel. Please follow the steps below to send a test webhook.

1. Navigate to Developers > Webhooks in your control panel.

2. Click the Send Test button.

3. Choose the type of webhook you'd like to send.

4. Provide a valid transaction ID if you've selected a payment webhook type, or enter a recurring payment reference if you've chosen a recurring payment webhook type.

5. Click the Send Test button.