Webhook Message

Netvalve provides real-time webhook information about the status of your requests. Setting up a webhook means you automatically receive updates when there is a status change with your request.

Webhook values

The Netvalve transmits the webhook message to the client server in JSON format.

{{
  "eventName": "PURCHASE_FAILED",
  "data": {
    "transactionType": "SALE",
    "clientOrderId": "791",
    "orderId": "141",
    "traceId": "05adf03e-a913-4082-a85d-efaaa77faf19",
    "midId": 2,
    "netvalveMidId": "04db4eeb-d1f1-473a-9f55-329a5c96f846",
    "responseTimestamp": "2024-03-21T10:45:02",
    "transactionId": null,
    "responseCode": null,
    "responseMessage": null,
    "responseCodeType": null,
    "amount": 11.10,
    "clientId": 2,
    "callbackConfigurationId": 1
  }
}

Event name

Possible event names

Event	Description

Event	Description
AUTHORISED	Triggered when a payment has been authorized
AUTHORISATION_FAILED	Triggered when the authorization process has failed
PURCHASED	Triggered when the Sale process has succeeded.
PURCHASE_FAILED	Triggered when Sale process has failed
CAPTURED	Triggered when an AUTHORISED payment has been CAPTURED, in full.
CAPTURE_FAILED	Triggered when the CAPTURE process has failed.
CANCELLATION_FAILED	When APM system, declines or fail for a payment, the event has been triggered
CANCELLED	Triggered when transaction is cancelled
REFUNDED	Triggered when a CAPTURED payment has subsequently been refunded.
REFUND_FAILED	Triggered when a REFUND request has failed.
REBILLED	Triggered when a REBILL transaction is successful
REBIL_FAILED	Triggered when a REBILL transaction is failed
AUTHORISATION_PENDING	Triggered when the authorization process has status PENDING
PURCHASE_PENDING	Triggered when Sale process has has status PENDING
CAPTURE_PENDING	Triggered when the CAPTURE process has has status PENDING
REBILL_PENDING	Triggered when a REBILL transaction has status PENDING
REFUND_PENDING	Triggered when a REFUND request has status PENDING
CANCELLATION_PENDING	Triggered when a CANCEL request has status PENDING

Webhook response

Webhook Request Handling:

^{For successful handling, your response to the POST request should be 200.}^OK.

^{Ensure that when consuming the webhook, the response is sent promptly to prevent a timeout.}

^{The timeout period is set to 5 seconds.}

Handling duplicates

You might get the same webhook event multiple times. This is normal because Netvalve uses a special delivery method called "at-least-once delivery." This means, Netvalve will keep sending the same event until your server successfully processes it and responds.

Even if your server accepts the event, it might not always respond in time (within 5 seconds). If this happens, Netvalve will assume the event wasn't handled and send it again later.

Delivery Attempts and Retries

Netvalve has two retry mechanisms to retry the messages. The first retry mechanism is the instant retry, it happens when we are processing the message for the first time and if it failed to be delivered it will be instantly retried 3 times. If the message failed to be delivered after the instant retries, the webhook message is going on the scheduled retry mechanism with these intervals:

15 minutes
30 minutes
1 hour
2 hours
4 hours
8 hours
16 hours
24 hours

Suspend/Disable

A webhook message is retried at progressive intervals of time on failure, for 24 hours. If the webhook continue to fail for 24 hours, the webhook is going in suspend state. Netvalve has multiple suspend intervals (1 day, 3 days, 5 days, 7 days), that means that after the first suspend state the webhook message will continue retrying after 1, 3, 5, 7 days, if the webhook message isn’t able to be delivered successfully, the callback configuration will be suspended and all the new messages will be on hold.

Order Of Events

Ideally, you should receive a webhook in the order in which the webhook events occur. However, you may not always receive the webhooks in order. Know more about Order of Webhooks.

Authentication

There are couple of ways to ensure authentication of the webhook.

Custom Header / Custom Header Value

When creating a new webhook, there’s an option to provide authentication header name (Custom Header) and value (Custom Header Value).
When the webhook request is sent to provided webhook URL, besides the request body with transaction details, it also includes provided custom header name and value.
Based on those 2 parameters, it’s possible to verify if the request is coming from verified server machine.

IP address restriction

Another mechanism of preventing requests from non-verified server machine would be to whitelist the IPs of those servers.
Netvalve is capable of providing the list of IPs that could be then verified on webhook receiver side to make sure requests are coming from verified server machine.