Webhooks

Kushki sends webhook notifications to your server for Card Present transaction events — charges, voids, and refunds. Your endpoint receives the event payload shortly after the terminal confirms the operation.

Configuration

Card Present webhooks are configured from the Kushki Console under Desarrolladores → Webhooks. Webhook configuration via API is not supported for Card Present.

Security

Encryption

You may use an HTTP or HTTPS URL for webhooks. HTTP is generally sufficient, but HTTPS is recommended if you handle sensitive data or want to protect against replay attacks.

Authentication

Anyone could, in principle, send a request to your endpoint — so it's important to verify that a notification actually originated from Kushki. Valid webhooks contain these headers:

Header	Description
`X-Kushki-Key`	Kushki ID of the merchant (found in the Console, Perfil → Servicios).
`X-Kushki-Id`	Date in Unix timestamp format.
`X-Kushki-Signature`	HMAC-SHA256 hex digest of the request body concatenated with `X-Kushki-Id`, signed with your Webhook Signature ID.
`X-Kushki-SimpleSignature`	HMAC-SHA256 hex digest of `X-Kushki-Id` alone, signed with your Webhook Signature ID.

You can use either X-Kushki-Signature or X-Kushki-SimpleSignature to verify authenticity — compare the header value against the signature you compute on your side using your Webhook Signature ID.

Where to find your Webhook Signature ID

Console → Perfil → Servicios → Identificadores → Webhook Signature.

Source IPs

Kushki sends webhook notifications from these static IPs — you can use them as an additional validation layer:

Environment	IP
Sandbox (UAT)	`54.208.105.247`
Production	`34.230.185.20`

Verifying the signature

Node.js — X-Kushki-Signature (body + timestamp):

Node.js — X-Kushki-SimpleSignature (timestamp only):

WARNING

Always verify the signature before trusting the payload. Reject any request where verification fails.

Idempotency

Kushki stores notifications on multiple servers for high availability. On rare occasions you may receive the same notification more than once.

WARNING

Design your webhook handler to be idempotent — processing the same notification twice must not produce duplicate side effects.

Webhook payload

Kushki reuses the same webhook mechanism as card transactions in general. The payload shape differs depending on the event:

Charge events (approved or declined)

Field names are in snake_case.

{
  "ticket_number": "111727462978861299",
  "transaction_id": "821730184348805573736",
  "transaction_reference": "0c291739-d93a-4e89-9b44-6de011c4fdb8",
  "amount": {
    "subtotalIva0": 10000,
    "subtotalIva": 0,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "currency_code": "CLP",
  "transaction_type": "SALE",
  "transaction_status": "APPROVAL",
  "created": 1727462978861,
  "merchant_id": "20000000109815430000",
  "merchant_name": "Mi Comercio Chile",
  "processor_id": "6000000000167692716389681607",
  "processor_name": "Kushki Acquirer Processor",
  "processor_type": "gateway",
  "last_four_digits": "5480",
  "approval_code": "676300",
  "request_amount": 10000,
  "approved_transaction_amount": 10000,
  "response_code": "000",
  "response_text": "Transacción aprobada",
  "card_holder_name": "Catalina Fuentes",
  "payment_brand": "MASTERCARD",
  "card_type": "credit",
  "issuing_bank": "BANCO SANTANDER CHILE",
  "foreign_card": false,
  "bin_card": "521892",
  "token": "dffddf9aa77549148d2450d0662c6e4b",
  "credential_alias": "Producción Chile",
  "credential_id": "45fe3a3ebe464ebb100f2aa344b6a095"
}

transaction_type is always "SALE" for a charge notification. transaction_status is "APPROVAL" or "DECLINED".

Void and refund events

Field names are in camelCase — a different casing convention than charge events.

{
  "ticketNumber": "661738684712571670",
  "transactionId": "700011575252919092",
  "transactionReference": "2052742c-97dc-4d8a-b7b0-27bf4eafcc0a",
  "amount": {
    "subtotalIva0": 0,
    "subtotalIva": 10000,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "currencyCode": "CLP",
  "transactionType": "VOID",
  "transactionStatus": "APPROVAL",
  "created": 1738684712892,
  "merchantId": "20000000109815430000",
  "merchantName": "Mi Comercio Chile",
  "processorId": "6000000000172166121420424728",
  "processorName": "Kushki Acquirer Processor",
  "processorType": "gateway",
  "lastFourDigits": "5480",
  "approvalCode": "000000",
  "requestAmount": 10000,
  "approvedTransactionAmount": 10000,
  "cardHolderName": "Catalina Fuentes",
  "paymentBrand": "MASTERCARD",
  "cardType": "credit",
  "binCard": "521892",
  "foreignCard": false,
  "voidTicketNumber": "661738684712571670",
  "saleTicketNumber": "029184246439606168",
  "saleApprovalCode": "000000"
}

transactionType is "VOID" or "REFUND". transactionStatus is "APPROVAL".

Testing your webhook

Interactions between endpoints over the internet can be complex — check that your webhook is working adequately before releasing it to production.

Check your webhook status

From the Kushki Console, go to Desarrolladores → Webhooks to see the list of webhooks you've created, including creation date, alias, the product/payment method it's configured for, and its connection status (Successful or Failed). Click the connection status label to see the URL and events configured for that webhook.

Simulate a test notification

Click Simulate connection on any webhook to send it a test notification — choose the payment method/product, the event, and the corresponding code to simulate.

Add custom headers

You can add up to 4 custom headers to any webhook, in addition to the headers Kushki sends by default:

Click the edit icon next to the webhook.

Add a label and value for your header, then click Save Webhook.

Click + to add another header (up to 4 total).

Best practices

Respond quickly. Return an HTTP 2xx as soon as you receive the notification, before running business logic — process asynchronously if needed.

Design for idempotency. Use ticket_number / ticketNumber as your deduplication key.

Verify the signature on every request. Don't trust the payload until X-Kushki-Signature or X-Kushki-SimpleSignature checks out.

Got a suggestion on this documentation? Contact us.

Security#

Encryption#

Authentication#

Source IPs#

Verifying the signature#

Idempotency#

Webhook payload#

Charge events (approved or declined)#

Void and refund events#

Testing your webhook#

Check your webhook status#

Simulate a test notification#

Add custom headers#

Best practices#

Security

Encryption

Authentication

Source IPs

Verifying the signature

Idempotency

Webhook payload

Charge events (approved or declined)

Void and refund events

Testing your webhook

Check your webhook status

Simulate a test notification

Add custom headers

Best practices