Webhooks Notification

Create new callback configuration

To set up a webhook that notifies you when a account, payment or invoice status changes, use the following endpoint.

POST https://sandbox-api.veem.com/veem/v1.2/webhooks

Request Payload

{
	"event":"OUTBOUND_PAYMENT_STATUS_UPDATED", 
	"callbackURL":"https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59"
}	

The following events are supported:

Response Payload

{
    "id": 31,
    "event": "OUTBOUND_PAYMENT_STATUS_UPDATED",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Active"
}

Update a callback configuration

For updating a webhook configuration you can use the following endpoint

PATCH https://sandbox-api.veem.com/veem/v1.2/webhooks/{webhookId}

Use the same headers described in Create new callback configuration section.

Request Payload

{
	"event":"OUTBOUND_PAYMENT_STATUS_UPDATED",
  "callbackURL":"https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59"
}

Response Payload

{
    "id": 31,
    "event": "OUTBOUND_PAYMENT_STATUS_UPDATED",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Active"
}

Get existing callback configurations

For querying the existent webhooks you can call the next endpoint

GET https://sandbox-api.veem.com/veem/v1.2/webhooks

Use the same headers described in Create new callback configuration section.

Response Payload

{
    "id": 31,
    "event": "OUTBOUND_PAYMENT_STATUS_UPDATED",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Active"
}

Delete a callback configuration

For deleting a webhook configuration use the following endpoint

DELETE https://sandbox-api.veem.com/veem/v1.2/webhooks/{webhookId}

Use the same headers described in Create new callback configuration section.

Response Payload

{
    "id": 31,
    "event": "OUTBOUND_PAYMENT_STATUS_UPDATED",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Inactive"
}

Getting the notifications

Once you configure the callbacks using the endpoints described above, Veem will start sending you notifications to the specified callbackUrl with the JSON payload. The structure of the data depends on the event type.

Here is a sample. Note that the data is returned in a stringified JSON format.

{
  "type":"INBOUND_PAYMENT_STATUS_UPDATED",
  "data":"{\"id\":1454408,\"invoiceId\":null,\"status\":\"InProgress\",\"debitTxn\":{\"id\":2001388,\"status\":\"Completed\",\"errorCode\":null,\"errorMessage\":null},\"creditTxn\":{\"id\":2001389,\"status\":\"Initiated\",\"errorCode\":null,\"errorMessage\":null},\"refundTxn\":null,\"payerFundingMethodType\":\"Wallet\",\"receiverFundingMethodType\":\"Wallet\",\"payerAccountId\":389111,\"payeeAccountId\":389111,\"originalRequestId\":\"7fe8a20b-e146-4801-89a2-b1317348396f\"}"
}

Verifying HMAC signature

We use HMAC 256 with clientId as key, and webhook payload to calculate an access signature hash value. The calculated signature is sent as a request header on each webhook notification for security purposes. An example of this header value is given below:

ACCESS_SIGNATURE eab9548a122de52e5b7a6f8c452df17d76824851ca0ea42900eb2b8c17a0fe2f

To verify that the webhook notification is coming from Veem, you can compare the ACCESS_SIGNATURE header value with the signature calculated on your end.

Here a java snippet of how the signature can be calculated:

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;

....
  
 
String signature = getSignature(payload, clientId); // compare signature with 'ACCESS_SIGNATURE' header value

......


    private String getSignature(String payload, String clientId) {
        String signature = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, clientId.getBytes()).hmacHex(payload);
        return signature;
    }

Retry Mechanism

The three webhooks mentioned above include a retry mechanism that attempts delivery up to three times, with a 5-second interval between each attempt.

Account status updated events

The Account Status Updated webhook is triggered whenever there is a change in the status of a user’s account within our system that impacts payments.

Event Name

ACCOUNT_STATUS_UPDATED

Payload Structure

The webhook will send a JSON payload in the following format:

{
  "id": 145553,
  "paymentReady": true,
  "verified": false
}

Parameters

See Create new callback configuration to setup this webhook.

Payment status updated events

When sending a payment request, developers can find out about the payment status by calling Get Payment Status. There will be times where "real time" updates are needed and webhooks can provide that. To leverage webhooks, you would need to register a callback URL that we will notify anytime an event happens to the payment.

For example, after a payment is sent by you, it would be in "PendingAuth" (or pending authorization) state. As it moves from "PendingAuth" to "Authorized", webhooks will post a notification that an event has occurred. You can then call Get Payment Status to find out the current state and other relevant details.

Event Name

INBOUND_PAYMENT_STATUS_UPDATED
OUTBOUND_PAYMENT_STATUS_UPDATED

Payload Structure

Note that data will be returned as stringified JSON. The example below shows the resulting JSON for illustration purposes.

{
  "type": "OUTBOUND_PAYMENT_STATUS_UPDATED",
  "data": {
    "id": 1,
    "invoiceId": 1,
    "status": "Authorized",
    "debitTxn": {
      "id": 1,
      "status": "Pending",
      "errorCode": "01345",
      "errorMessage": "In case of reversal"
    },
    "creditTxn": {
      "id": 2,
      "status": "Pending",
      "errorCode": "01345",
      "errorMessage": "In case of reversal"
    }
  }
}

Parameters

The table below provides detailed information about the payload parameters, including parameter names and formatting (when applicable). It clarifies the specific parameters you can expect to see in the notification.

Payment Status

To understand the various payment statuses, here is a mapping of the webhooks notifications to what is shown in the customer UI. Note that from time to time there might be updates/changes to how the statuses are presented to the customer to optimize the experience. The statuses received via webhooks will not change to ensure backwards compatibility.

Invoice status updated events

The Invoice Status Updated webhook is triggered whenever an invoice undergoes a status change.

Event Name

INBOUND_INVOICE_STATUS_UPDATED
OUTBOUND_INVOICE_STATUS_UPDATED

Payload Structure

Note that data will be returned as stringified JSON. The example below shows the resulting JSON for illustration purposes.

{
  "type": "INBOUND_INVOICE_STATUS_UPDATED",
  "data": {
    "id": 124585,
    "status": "Sent",
    "amount": {
        "number": 500.00,
        "currency": "USD"
    },
    "payerAccountId": 36699,
    "payeeAccountId": 14521,
    "dueDate": "2025-01-01",
    "scheduledSentDateIso": "2025-01-01",
    "paymentId": 123
  }
}

Invoice Status

updated at (2025-12-02T01:12:02.984Z)