Webhooks
Monek uses Svix to send secure webhook notifications to merchants when important transaction events occur, including sales, refunds, and reversals.
Configure Webhook
To receive webhook notifications you'll need a public HTTP POST URL on your server that can receive and process the webhook JSON payloads.
Your webhook URL can be registered via the Monek Portal on the Setting\Integrations page.
This functionality is currently in pilot. To enable this option for your merchant please contact Monek Support
Webhook Payload
Each webhook event includes detailed transaction data
Name | Description |
---|---|
Data | The main Webhook node containing transaction details. See Webhook Data. |
EventId | Unique identifier for this webhook and also the Monek Cross Reference for this transaction. |
EventType | The type of event this webhook contains. See Event Types. |
Metadata | Additional information relating to this webhook. |
Timestamp | The data and time of the transaction represented by this webhook. |
Webhook Data
Name | Description |
---|---|
Amount | The transaction amount minor currency. |
AuthorisationCode | The authorisation code for a successful transaction. |
AvsCv2Description | Description of the AVS/CV2 check result. |
AvsCv2Result | Raw code for the AVS/CV2 result. See AVS/CV2 Response Values. |
CardType | Card type code. See Card Type Values. |
CardholderAddress | The cardholder's billing address. |
CardholderEmail | The cardholder's email address. |
CardholderName | The cardholder's name. |
CardholderPhoneNumber | The cardholder's phone number. |
CountryCode | The merchant's country code. |
CrossReference | The unique character string returned by TransactDirect to identify this transaction. |
CurrencyCode | The currency code used for the transaction. |
IdempotencyToken | The idempotency token specified for this transaction. |
Last4Digits | The last 4 digits of the payment card. |
MerchantData | Additional merchant data provided by the merchant. Typically JSON or Base64 encoded. |
MerchantName | The merchant name. |
Message | Message indicating the result of this transaction. |
MessageType | The message type for this transaction. See Message Types. |
MonekId | The Monek Merchant ID for this merchant. |
ParentReference | Contains the Cross Reference of the originating transaction. e.g. For completion of Pre-Auth, or Refund or Recharge of a previous transaction. |
PaymentChannel | Payment channel provided by the merchant for this transaction. |
PaymentDetail | Additional payment details provided by the merchant. Typically JSON or Base64 encoded. |
PaymentReference | The ID provided by the merchant to identify the transaction. |
ResponseCode | The TransactDirect response code. See Response Code Values. |
ThreeDSecureResult | The 3-D Secure transaction result code. |
ThreeDSecureVersion | The 3-D Secure version used. |
TransactionDateTime | The date and time this transaction was processed. |
Webhook Example
{
"Data": {
"Amount": "1",
"AuthorisationCode": "713871",
"AvsCv2Description": "SECURITY CODE MATCH ONLY",
"AvsCv2Result": "211100",
"CardType": "VC",
"CardholderAddress": "",
"CardholderEmail": "test@monek.com",
"CardholderName": "Test Cardholder Name",
"CardholderPhoneNumber": "",
"CountryCode": "826",
"CrossReference": "250613125457713871GD4",
"CurrencyCode": "826",
"IdempotencyToken": "177834ab-55f4-4caa-a4f7-3e789d81d9fe",
"Last4Digits": "0216",
"MerchantData": "",
"MerchantName": "Test Account",
"Message": "AUTH CODE:713871",
"MessageType": "SALE_CNP_TO[INTERNET]",
"MonekId": "0000893",
"ParentReference": "",
"PaymentChannel": "",
"PaymentDetail": "Test VT",
"PaymentReference": "Test VT",
"ResponseCode": "00",
"ThreeDSecureResult": "",
"ThreeDSecureVersion": "",
"TransactionDateTime": "2025-06-13T12:54:57.36+00:00"
},
"EventId": "250613125457713871GD4",
"EventType": "sale.success",
"Metadata": {
"Application": {
"Name": "Test Account",
"PayloadRetentionPeriod": 90,
"Source": "Monek.PaymentService",
"Uid": "0000893"
}
},
"Timestamp": "2025-06-13T12:54:57.36+00:00"
}
Event Types
Each webhook includes an EventType field which indicates the type of transaction and result of the transaction in the form type.result
. For example sale.success
would indicate a sale transaction that was successfully authorised.
Type | Description |
---|---|
sale | A sale transaction |
verify | An account verification transaction |
refund | A refund transaction |
reversal | A transaction reversal |
unknown | An unknown or unsupported transaction type. e.g. When an invalid message type was used |
Result | Description |
---|---|
success | Transaction was successful |
refer | Transaction was referred for further checks |
decline | Transaction was declined |
error | An error occurred processing this transaction |
Handle new or unknown types defensively. For example by logging them for review and implementation.
Verifying Webhook Authenticity
Because of the way webhooks work, attackers can impersonate services by simply sending a fake webhook to an endpoint. This is a potential security hole for many applications.
In order to prevent it, every webhook and its metadata is signed with a unique key for each endpoint. This signature can then be used to verify the webhook is genuine.
There are two options to verify authenticity
Verify Webhooks with Svix Libraries
Details on how to verify webhooks using Svix libraries are available at How to Verify Webhooks with the Svix Libraries
Examples are provided for various languages including C#, PHP, Python, JavaScript, and more.
Manual Verification
Advanced integrations may implement their own HMAC-based signature checking. Learn more about this at Verifying Webhooks Manually.
Secret Key
Your secret key is available via the Svix Dashboard. You can rotate your secret key there at any time.
Source IP Addresses
In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from Svix's Static Source IP addresses.
Current IP Addresses (EU Region)
52.215.16.239
54.216.8.72
63.33.109.123
2a05:d028:17:8000::/56