Webhook

Webhooks are a method for your application to receive real-time updates whenever specific events occur on our platform. Unlike traditional API requests where you must poll for data, webhooks push data to your system as soon as an event happens, enabling more efficient and responsive integrations.

What is a Webhook?

A webhook is an HTTP callback that allows you to subscribe to events and receive notifications to a specified URL. When an event is triggered, such as a payment status change, our platform will send an HTTP POST request to the configured endpoint with details of the event.

How Do Webhooks Work?

1. Subscription: You register your endpoint URL through our API dashboard or via an API request to start receiving updates.

2. Event Occurrence: An event is triggered in the system, such as a payment status update.

3. Notification: A POST request containing event details is sent to your endpoint.

4. Response: Your server should respond with a 2xx HTTP status code to acknowledge successful receipt. Non-2xx responses will trigger retries based on our retry policy.

Use Cases for Webhooks

1. Real-time Payment Status Updates: Receive notifications when a payment is initiated, processed, or completed.

2. Cancellation Alerts: Get notified if a payment requires additional verification.

3. Error Handling: Be alerted when a payment fails so corrective actions can be taken.

Getting Started with Webhooks

1. Setting Up Your Endpoint

• Ensure your endpoint is HTTPS and publicly accessible.
• Implement security measures such as validating source IPs or using a secret token for verification.

2. Subscribing to Webhooks

Use our webhook endpoint with POST method to subscribe to our webhook.

Currently you can subscribe to the following event type(s):

• PaymentStatusChanged

{
  "eventType": "PaymentStatusChanged",
  "url": "https://example.com/914f37d3",
  "isActive": true
}

3. Receiving and Handling Webhooks

• Your server should be configured to accept POST requests and parse the payload. A sample payload for a PaymentStatusChanged event may look like this:

{
  "specversion": "v1.0",
  "type": "PaymentStatusChanged",
  "source": "StoneX Payments",
  "id": "9c4ddfff-731d-43dc-89fe-5f018d06b234",
  "datacontenttype": "application/json",
  "time": "2024-11-07T11:18:18.615081+00:00",
  "data": {
    "fxId": 4779058,
    "clientReference": "TestRef",
    "tradeStatus": "PENDINGINSTRUCTION",
    "uetr": "15e4e124-5b9b-4ffe-9f9d-eebdf6bde43v",
    "reimbursementStatus": "PENDING",
    "paymentStatus": "Processing",
    "paymentStatusDescription": "",
    "gpiCode": "",
    "gpiStatus": "",
    "tradeDate": "2024-11-07",
    "valueDate": "2024-11-07"
  }
}

• Respond with a 2xx status code to acknowledge receipt:

HTTP/1.1 200 OK

Security Best Practices

• Verify the Source: Validate the request comes from our platform by checking for a unique signature or token in the headers.
• Use HTTPS: Always use HTTPS to secure the transmission of data.
• Log Incoming Webhooks: For troubleshooting and monitoring, log the payload and responses.