Webhooks

Webhooks enable real-time notifications when transaction statuses change.

‍

Overview

The Revio API allows you to:

• Configure webhook URLs for different event types
• Receive real-time callbacks when collections or payments change status
• Test webhook integrations in the sandbox environment

‍

There is no limit to the number of webhooks you can configure.

‍

Callback Types

‍

Step 1: Create Callback URL

Register a URL to receive webhook notifications.

‍

Endpoint

POST /v2/clientcallbackurl/

‍

Request

BASH

curl -X POST https://dev.api.revio.co.za/v2/clientcallbackurl/ \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "clientId": 109,
   "url": "https://your-server.com/webhooks/revio",
   "callbackType": "EFT_COLLECTION",
   "callbackVersion": "V2"
 }'


‍

Request Fields

‍

Response

JSON

{
 "id": "callback-url-123",
 "clientId": 109,
 "url": "https://your-server.com/webhooks/revio",
 "callbackType": "EFT_COLLECTION",
 "callbackVersion": "V2"
}


‍

Register Multiple Callback Types

Create separate callback URLs for each event type:

‍

BASH

# EFT Collections
curl -X POST https://dev.api.revio.co.za/v2/clientcallbackurl/ \
 -d '{"clientId": 109, "url": "https://...", "callbackType": "EFT_COLLECTION", "callbackVersion": "V2"}'

# DebiCheck Collections
curl -X POST https://dev.api.revio.co.za/v2/clientcallbackurl/ \
 -d '{"clientId": 109, "url": "https://...", "callbackType": "DEBICHECK_COLLECTION", "callbackVersion": "V2"}'

# DebiCheck Mandates
curl -X POST https://dev.api.revio.co.za/v2/clientcallbackurl/ \
 -d '{"clientId": 109, "url": "https://...", "callbackType": "DEBICHECK_MANDATE", "callbackVersion": "V2"}'

# EFT Payments
curl -X POST https://dev.api.revio.co.za/v2/clientcallbackurl/ \
 -d '{"clientId": 109, "url": "https://...", "callbackType": "EFT_PAYMENT", "callbackVersion": "V2"}'



‍

Step 2: Trigger Callback Event

Trigger a callback for a specific collection (useful for re-sending notifications).

‍

Endpoint

POST /v2/callback/collection/eft/{collectionId}/

‍

Request

BASH

curl -X POST https://dev.api.revio.co.za/v2/callback/collection/eft/63d94be3-1faf-428b-89f3-bc5271be8015/ \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "collectionStatus": "UNPAID",
   "callbackVersion": "V2"
 }'


‍

This sends the current collection status to your configured callback URL.

‍

Step 3: Test Callback (Sandbox)

Simulate callback events to test your webhook handler without affecting actual transactions.

‍

Endpoint

POST /v2/callback/test/collection/eft/{collectionId}/

‍

Request

BASH

curl -X POST https://dev.api.revio.co.za/v2/callback/test/collection/eft/63d94be3-1faf-428b-89f3-bc5271be8015/ \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "collectionStatus": "UNPAID",
   "callbackVersion": "V2"
 }'


‍

Request Fields

‍

Override URL Example

Send test callback to a different URL:

‍

JSON

{
 "overrideUrl": "https://webhook.site/your-test-id",
 "collectionStatus": "COMPLETED",
 "callbackVersion": "V2"
}


‍

Callback Payload

When a status change occurs, Revio sends a POST request to your webhook URL.

‍

EFT Collection Callback

JSON

{
 "id": "63d94be3-1faf-428b-89f3-bc5271be8015",
 "type": "EFT_COLLECTION",
 "status": "COMPLETED",
 "mandateId": "8f4a6b0f-fa9b-4f45-8e19-b75c1a70432a",
 "contractReference": "CONTRACT001",
 "amountCents": 10000,
 "collectionDate": "2024-02-15T00:00:00.000Z",
 "statementId": "stmt_12345",
 "timestamp": "2024-02-15T14:30:00.000Z"
}


‍

DebiCheck Mandate Callback

JSON

{
 "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "type": "DEBICHECK_MANDATE",
 "status": "COMPLETED",
 "contractReference": "DC001",
 "authenticationType": "REALTIME",
 "timestamp": "2024-02-15T14:30:00.000Z"
}


‍

DebiCheck Collection Callback

JSON

{
 "id": "coll-123-456-789",
 "type": "DEBICHECK_COLLECTION",
 "status": "COMPLETED",
 "mandateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "amountCents": 10000,
 "timestamp": "2024-02-15T14:30:00.000Z"
}


‍

Handling Webhooks

Webhook Handler Example (Node.js)

JSX

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/revio', (req, res) => {
 const event = req.body;

 console.log('Received webhook:', event.type, event.status);

 switch (event.type) {
   case 'EFT_COLLECTION':
     handleEftCollection(event);
     break;
   case 'DEBICHECK_COLLECTION':
     handleDebicheckCollection(event);
     break;
   case 'DEBICHECK_MANDATE':
     handleDebicheckMandate(event);
     break;
   case 'EFT_PAYMENT':
     handleEftPayment(event);
     break;
 }

 // Always respond with 200 OK
 res.status(200).send('OK');
});

function handleEftCollection(event) {
 if (event.status === 'COMPLETED') {
   // Mark payment as successful in your system
 } else if (event.status === 'UNPAID') {
   // Handle failed collection
 }
}


‍

Best Practices

1. Respond quickly: Return 200 OK within 5 seconds
2. Process asynchronously: Queue events for background processing
3. Handle duplicates: Implement idempotency using the event ID
4. Verify source: Validate requests originate from Revio
5. Log everything: Keep detailed logs for debugging
6. Retry handling: Handle the same event being sent multiple times

‍

Webhook Security

URL Requirements

• Must use HTTPS
• Must be publicly accessible
• Should respond within 5 seconds

‍

Recommendations

1. Use a unique path: Include a secret in your webhook URL
2. Validate payloads: Check expected fields are present
3. Monitor failures: Alert on repeated delivery failures

‍

Testing Tools

Use these services to test webhooks during development:

• Webhook.site - Free webhook testing
• RequestBin - Inspect webhook payloads
• ngrok - Expose local servers

‍

Example with Webhook.site

1. Go to webhook.site and copy your unique URL
2. Register it as your callback URL:

‍

BASH

curl -X POST https://dev.api.revio.co.za/v2/clientcallbackurl/ \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "clientId": 109,
   "url": "https://webhook.site/your-unique-id",
   "callbackType": "EFT_COLLECTION",
   "callbackVersion": "V2"
 }'


‍

1. Trigger a test callback to see the payload

‍

Troubleshooting

Common Issues

‍

Verify Callback Registration

Get your client ID from merchant profile:

‍

BASH

curl -X GET https://dev.api.revio.co.za/v2/merchantprofile/ \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"


‍

The createdByClient field is your client ID for webhook registration.