Webhooks

What are webhooks?

Eversend triggers events that your application can listen to whenever certain actions occur on your Eversend Transactions. Here's where webhooks come in handy. We deliver payloads for such events to a webhook URL on your server. If you use webhooks, for example, we'll send a transaction.success event to your server as soon as a transaction status is retrieved.

You can specify your webhook URL from the Settings Page on your dashboard where we would send POST requests whenever an event occurs.

Here are some things to note when setting up a webhook URL:

Do a test post to your URL and ensure the script gets the post body.
Ensure your webhook URL is publicly available (localhost URLs cannot receive events)

Setup webhooks

To set up a new webhook:

From the Eversend dashboard, click the settings bar and select the developers' tab.
Enter your webhook URL to generate a web secret.

Webhook URL: the URL to receive the webhook notifications.
Webhook Secret: a secret key to pass along to the request header in order to make your webhook endpoint protected.

Click Submit to save changes.
✳️ Done! The webhook is now set up and your application will be notified of new events related to any product opted for.

Receiving an event

A valid request from Eversend has the header X-Eversend-Signature which is a HMAC SHA512 hash of the payload. You can verify the request by hashing the payload body with your secret key and comparing it to the value of X-Eversend-Signature. Below is a sample code in Node.js using the Express framework.

const hash = require('crypto')
  .createHash('sha512', 'webhookSecret')
  .update(req.body).digest('hex');
if (hash !== req.header['x-eversend-signature`]) {
  return res.status(401).send('Unauthorized request!');
}
// Do something
return res.status(200).send('Success!');

A 200 OK should be used to respond to an event. This is considered an acknowledgement of your application. If your application returns a status other than 2xx, we will consider it an unauthorized request and will send a webhook when there's a status update.

🚧
Note
Headers tend to be automatically converted to lowercase as per HTTP/2 specifications.

Example incoming webhook for Fiat Transactions

Below you will see an example of an incoming webhook from Eversend servers for fiat transactions. We currently send transaction events only.

{
  "type": "transaction.status",
  "data": {
    "transactionId": "XX31646037316450",
    "transactionRef": "XY-12345678",
    "type": "payout",
    "currency": "UGX",
    "amount": "2000",
    "balanceBefore": "7134.94",
    "balanceAfter": "4134.94",
    "destinationCurrency": "UGX",
    "destinationAmount": "2000",
    "destinationCountry": "UG",
    "beneficiary": {
      "id": 16,
      "firstName": "John",
      "lastName": "Doe",
      "isEversend": false,
      "isBank": false,
      "isMomo": true,
      "country": "UG",
      "phoneNumber": "+256712345678",
      "bankName": null,
      "bankCode": null,
      "bankAccountName": null,
      "bankAccountNumber": null,
      "isDeleted": false,
      "createdAt": "2022-02-21T13:50:53.914Z",
      "updatedAt": "2022-02-21T13:50:53.915Z",
    },
    "status": "pending",
    "createdAt": "2022-02-28T08:35:21.129Z",
    "updatedAt": "2022-02-28T18:22:50.748Z",
  }
}

{
  "type": "transaction.status",
  "data": {
    "transactionId": "XX31646037316450",
    "transactionRef": "XY-12345678",
    "type": "payout",
    "currency": "UGX",
    "amount": "2000",
    "balanceBefore": "7134.94",
    "balanceAfter": "4134.94",
    "destinationCurrency": "UGX",
    "destinationAmount": "2000",
    "destinationCountry": "UG",
    "beneficiary": {
      "id": 16,
      "firstName": "John",
      "lastName": "Doe",
      "isEversend": false,
      "isBank": false,
      "isMomo": true,
      "country": "UG",
      "phoneNumber": "+256712345678",
      "bankName": null,
      "bankCode": null,
      "bankAccountName": null,
      "bankAccountNumber": null,
      "isDeleted": false,
      "createdAt": "2022-02-21T13:50:53.914Z",
      "updatedAt": "2022-02-21T13:50:53.915Z",
    },
    "status": "successful",
    "createdAt": "2022-02-28T08:35:21.129Z",
    "updatedAt": "2022-02-28T18:22:50.748Z"
  }
}

{
  "type": "transaction.status",
  "data": {
    "transactionId": "XX31646037316450",
    "transactionRef": "XY-12345678",
    "type": "payout",
    "currency": "UGX",
    "amount": "2000",
    "balanceBefore": "7134.94",
    "balanceAfter": "4134.94",
    "destinationCurrency": "UGX",
    "destinationAmount": "2000",
    "destinationCountry": "UG",
    "beneficiary": {
      "id": 16,
      "firstName": "John",
      "lastName": "Doe",
      "isEversend": false,
      "isBank": false,
      "isMomo": true,
      "country": "UG",
      "phoneNumber": "+256712345678",
      "bankName": null,
      "bankCode": null,
      "bankAccountName": null,
      "bankAccountNumber": null,
      "isDeleted": false,
      "createdAt": "2022-02-21T13:50:53.914Z",
      "updatedAt": "2022-02-21T13:50:53.915Z",
    },
    "status": "failed",
    "createdAt": "2022-02-28T08:35:21.129Z",
    "updatedAt": "2022-02-28T18:22:50.748Z"
  }
}

Example incoming webhook for Crypto Transactions

Below you will see an example of an incoming webhook from Eversend servers for crypto transactions. We currently send transaction events only.

{
    data: {
        id: "1cab0836-6f1f-45e4-94b6-e74ac9f26072",
        amount: 100,
        status: "CONFIRMING",
        txHash: "4ca89a0d9f4de130b604e857728ac21847f20aac2feba55034bfd63cf4cbd6c4",
        assetId: "TRX_USDT_S2UZ",
        feeInfo: {
            networkFee: "0"
        },
        amountUSD: 100.1,
        blockInfo: {
            blockHash: "000000000366963ffd66bdca0de2b2531abb57aa35d27faa0d070c72ff149cfe",
            blockHeight: "57054783"
        },
        createdAt: 1701797279361,
        netAmount: 100,
        operation: "TRANSFER",
        subStatus: "PENDING_BLOCKCHAIN_CONFIRMATIONS",
        amountInfo: {
            amount: "100",
            amountUSD: "100.10",
            netAmount: "100",
            requestedAmount: "100"
        },
        networkFee: 0,
        addressType: "",
        feeCurrency: "TRX",
        lastUpdated: 1701797279390,
        destinations: [],
        exchangeTxId: "",
        externalTxId: null,
        customerRefId: null,
        sourceAddress: "TQrY8tryqsYVCYS3MFbtffiPp2ccyn4STm",
        destinationTag: "",
        signedMessages: [],
        requestedAmount: 100,
        destinationAddress: "TMcmMgNXndKNanpoLEQJhE91EwrC1sXn1s",
        numOfConfirmations: 1,
        destinationAddressDescription: ""
    },
    purpose: null,
    tenantId: "EVS00000512",
    ownerName: null,
    timestamp: 1701797289703,
    destinationAddressDescription: null
}

{
    data: {
        id: "1cab0836-6f1f-45e4-94b6-e74ac9f26072",
        amount: 100,
        status: "COMPLETED",
        txHash: "4ca89a0d9f4de130b604e857728ac21847f20aac2feba55034bfd63cf4cbd6c4",
        assetId: "TRX_USDT_S2UZ",
        feeInfo: {
            networkFee: "0"
        },
        amountUSD: 100.1,
        blockInfo: {
            blockHash: "000000000366963ffd66bdca0de2b2531abb57aa35d27faa0d070c72ff149cfe",
            blockHeight: "57054783"
        },
        createdAt: 1701797279361,
        netAmount: 100,
        operation: "TRANSFER",
        subStatus: "CONFIRMED",
        amountInfo: {
            amount: "100",
            amountUSD: "100.10",
            netAmount: "100",
            requestedAmount: "100"
        },
        networkFee: 0,
        addressType: "",
        feeCurrency: "TRX",
        lastUpdated: 1701797279599,
        destinations: [],
        exchangeTxId: "",
        externalTxId: null,
        customerRefId: null,
        sourceAddress: "TQrY8tryqsYVCYS3MFbtffiPp2ccyn4STm",
        destinationTag: "",
        signedMessages: [],
        requestedAmount: 100,
        destinationAddress: "TMcmMgNXndKNanpoLEQJhE91EwrC1sXn1s",
        numOfConfirmations: 1,
        destinationAddressDescription: ""
    },
    purpose: null,
    tenantId: "EVS00000512",
    ownerName: null,
    timestamp: 1701797291698,
    destinationAddressDescription: null
}

Example incoming webhook for Card Transactions

Below you will see an example of an incoming webhook from Eversend servers for card transactions. We currently send transaction events only.

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "processor": "visa",
  "balance": 2,
  "amount": 5,
  "cardAcceptorName": "aliexpress",
  "currencyCode": "USD",
  "cardAcceptorCity": "Lagos",
  "authorizationCurrencyCode": "USD",
  "eventType": "card.authorization"
}

{
  "email": "[email protected]",
  "amount": 5,
  "currency": "USD",
  "network": "visa",
  "name": "aliexpress",
  "city": "New York",
  "state": "New York",
  "zip": 10222,
  "message": "not successful",
  "country": "United States",
  "availableBalance": 2,
  "authorizationAmount": 5,
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "eventType": "card.authDeclined"
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Terminated",
  "activated": false,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.terminated"
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Active",
  "activated": true,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.adjusted",
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Active",
  "activated": true,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.adjusted"
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Inactive",
  "activated": true,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.adjusted",
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Active",
  "activated": true,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.subscriptionReminder"
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Active",
  "activated": true,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.subscriptionFailed"
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Active",
  "activated": true,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.subscriptionRenewal"
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Active",
  "activated": true,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.cardFxCharge"
}

{
  "email": "[email protected]",
  "cardId":"1c866db9-fb38-4e8d-aac1-08dbe11e1a1d",
  "cardStatus": "Card - Active",
  "activated": true,
  "accountLimit": 8,
  "balance": 1,
  "eventType": "card.adjusted"
}

What are webhooks?

Setup webhooks

Receiving an event

🚧Note

Example incoming webhook for Fiat Transactions

Example incoming webhook for Crypto Transactions

Example incoming webhook for Card Transactions

🚧
Note