Webhooks

Webhooks deliver the final result of a transaction to your server in real time. Because POST /api/payments/performTransaction returns only PROCESS/100, a registered webhook is how you learn whether a transaction was approved or declined.

The flow is: generate a signed URL, register it for a terminal, then receive callbacks on your server. A testing endpoint lets you fire a simulated notification before going live.

Generate webhook URL — POST /api/webhooks/generate-url

Generates a signed webhook URL with HMAC-SHA256 authentication.

Request parameters

Request

{
  "clientId": "merchant1",
  "terminalId": "8184000200000077",
  "secretKey": "pos123",
  "baseUrl": "https://app.hooklistener.com",
  "webhookPath": "w/my-first-endpoint-2mtj",
  "signatureAlgorithm": "HMAC_SHA256",
  "tokenExpiryHours": "24",
  "retryAttempts": "3"
}

Response

{
  "success": true,
  "message": "Webhook URL generated successfully",
  "webhookUrl": "https://app.hooklistener.com/w/my-first-endpoint-2mtj?token=...",
  "generatedAt": "2026-03-25T12:24:38.997616332",
  "expiresAt": "2026-03-26T12:24:38.997616332",
  "details": {
    "webhookPath": "w/my-first-endpoint-2mtj",
    "baseUrl": "https://app.hooklistener.com",
    "clientId": "merchant1",
    "terminalId": "8184000200000077",
    "tokenExpiryHours": 24,
    "retryAttempts": 3,
    "algorithm": "HMAC_SHA256"
  }
}

Register webhook — POST /api/webhooks/register

Registers a webhook URL to receive transaction notifications for a terminal.

Request parameters

Request

{
  "terminalId": "8184000200000077",
  "callbackUrl": "https://app.hooklistener.com/w/my-first-endpoint-2mtj?token=...",
  "secretKey": "pos_secret_123"
}

Response

{
  "status": "SUCCESS",
  "message": "Webhook URL registered successfully",
  "terminalId": "8184000200000077",
  "callbackUrl": "https://app.hooklistener.com/w/my-first-endpoint-2mtj?token=...",
  "registeredAt": "2025-12-26T05:50:29.928462500Z",
  "instructions": "You will receive webhook notifications at this URL",
  "registrationInfo": {
    "clientIdentifier": "merchant1",
    "terminalId": "8184000200000077",
    "registeredAt": "2025-12-26T05:50:29.927467300Z",
    "expiresAt": "2025-12-27T05:50:29.927467300Z",
    "isExpired": "false",
    "secretPresent": "true"
  }
}

Receive webhook notification — POST /api/webhooks/receive?token={token}

This is the endpoint on your server that receives real-time transaction notifications from the middleware. The token query parameter is required for authentication and is included automatically in the generated webhook URL. The middleware calls this endpoint when a transaction completes.

Request parameters (all optional; populated per transaction)

Request

{
  "transactionId": "TXN1001",
  "transactionType": "PURCHASE",
  "panNumber": "455********676",
  "transactionAmount": "150"
}

Notify webhook (testing) — POST {registeredWebhookUrl}

For testing only. Call this using the full registered webhook URL (including its token) as the endpoint — the same URL returned by Generate Webhook URL and stored during Register Webhook. Sending a POST with a simulated transaction body lets you verify your receiver processes notifications correctly before live transactions occur.

POST https://app.hooklistener.com/w/my-first-endpoint-2mtj?token=bmFtaTo4MTg0MD...

Request parameters (all optional)

Request

{
  "transactionId": "TXN1001",
  "transactionType": "PURCHASE",
  "panNumber": "455********676",
  "transactionAmount": "150"
}

Response

{
  "message": "Notification sent successfully",
  "status": "SUCCESS"
}

📘

Verify the signature on every callback

Webhook URLs are signed with HMAC-SHA256 using your secretKey. Validate the signature on each received notification before trusting its contents, and have your receiver tolerate retries (retryAttempts) idempotently using transactionId / rrn.