Webhooks overview

Our webhook service enables you to receive instant notifications for critical events in your referral workflow. This integration helps ensure immediate awareness of referral creation and processing status, allowing for real-time response to referral outcomes.

Webhook Events

Referral Created Event

The REFERRAL_CREATED webhook event is sent when a referral is created successfully. This event helps you track the status of your referrals in real-time.

Event Details

Event Name: REFERRAL_CREATED

Trigger Conditions:

• Successful referral creation from a referral
• Failed referral creation due to validation or system errors

Response Status:

• CREATED: Referral was successfully created
• FAILED: Referral creation failed (includes failure message)

Success Payload Example

1
{
2
  "partner_id": "0201110000749410",
3
  "additional_details": {
4
    "client_reference_id": "REF120536",
5
    "country_moving_to": "USA",
6
    "ccy_pair": "GBPUSD",
7
    "etv": "50,000 - 100,000",
8
    "service_required": "Other"
9
  },
10
  "contact": {
11
    "last_name": "Daviess1",
12
    "phone_number": "+614455666544",
13
    "mobile_number": "+447128645157",
14
    "first_name": "Joes2",
15
    "email": "usertest126@example.com",
16
    "date_of_birth": "1995-06-01",
17
    "address": {
18
      "street": "123 High Street",
19
      "city": "London",
20
      "post_code": "SW1A 1AA",
21
      "country": "UK",
22
      "state": ""
23
    }
24
  },
25
  "referral_date": "2025-05-20T19:14:05.878",
26
  "referral_id": "2cd722f4-c42a-4238-86fb-541575371ef8",
27
  "company": {
28
    "name": "Downweed Ltd.",
29
    "registration_number": "3283273"
30
  },
31
  "event_name": "REFERRAL_CREATED",
32
  "status": "CREATED"
33
}

Failure Payload Example

1
{
2
  "partner_id": "0201110000749410",
3
  "additional_details": {
4
    "client_reference_id": "REF120536",
5
    "country_moving_to": "USA",
6
    "ccy_pair": "GBPUSD",
7
    "etv": "50,000 - 100,000",
8
    "service_required": "Other"
9
  },
10
  "contact": {
11
    "last_name": "Daviess1",
12
    "phone_number": "+614455666544",
13
    "mobile_number": "+447128645157",
14
    "first_name": "Joes2",
15
    "email": "usertest126@example.com",
16
    "date_of_birth": "1995-06-01",
17
    "address": {
18
      "street": "123 High Street",
19
      "city": "London",
20
      "post_code": "SW1A 1AA",
21
      "country": "UK",
22
      "state": ""
23
    }
24
  },
25
  "referral_date": "2025-05-20T19:14:40.021",
26
  "referral_id": "064dc9ed-5398-4969-bb64-f1d27a686a9e",
27
  "company": {
28
    "name": "Downweed Ltd.",
29
    "registration_number": "3283273"
30
  },
31
  "event_name": "REFERRAL_CREATED",
32
  "failure_message": "DUPLICATE_VALUE - duplicate value found- client_reference_id duplicates value on record with id- 00QUD00000EgWTG2A3",
33
  "status": "FAILED"
34
}

Implementation Guide

Authentication

Each webhook request includes a signature header to verify its authenticity. Here’s how to verify the signature in different languages:

Java (using Svix Java SDK)

1
Svix svix = new Svix("<YOUR_SVIX_SECRET>");
2
Webhook webhook = new Webhook("<YOUR_SIGNING_SECRET>");
3
String payload = requestBody;
4
String header = request.getHeader("svix-signature");
5
webhook.verify(payload, header); // throws exception if invalid

Node.js

1
const { Webhook } = require("@svix/webhooks");
2
const webhook = new Webhook("<YOUR_SIGNING_SECRET>");
3
const payload = req.body;
4
const headers = req.headers["svix-signature"];
5
webhook.verify(JSON.stringify(payload), headers);

Python

1
from svix.webhooks import Webhook
2
wh = Webhook("<YOUR_SIGNING_SECRET>")
3
headers = request.headers["svix-signature"]
4
payload = request.data
5
wh.verify(payload, headers)

Best Practices

Integration Tips

• Set up proper error handling for webhook processing
• Implement signature verification
• Store webhook events for audit purposes
• Return 2xx status codes to acknowledge receipt

Implementation Steps

1. Configure Webhook Endpoint

   • Set up a publicly accessible HTTPS endpoint to receive webhook events

2. Implement Signature Verification

   • Verify the signature of each incoming webhook request using your signing secret

3. Process the Webhook

   • Parse and process the webhook payload based on the event type

4. Acknowledge Receipt

   • Return a 2xx status code to acknowledge successful receipt of the webhook

Error Handling

Common Failure Scenarios

• Signature Verification Failures:

  • Ensure you’re using the raw request body for signature verification
  • Verify that all required headers are present and correctly formatted
  • Use the official Svix SDKs for reliable verification

• Payload Processing Errors:

  • Validate the webhook payload against the expected schema
  • Check for required fields like customer_type
  • Implement comprehensive error handling for malformed data

• Server Errors (5xx):

  • Monitor your logs for processing errors
  • Implement proper error reporting
  • Set up alerts for repeated failures

• Client Errors (4xx):

  • Verify your endpoint is properly configured
  • Check authentication credentials
  • Validate request formatting

Retry Policy