Receiving Webhooks

Webhooks are a crucial part of the StableMint payment flow, providing real-time notifications about payment initiation or withdrawal request status changes.

Overview

Webhooks allow your application to receive automatic notifications when certain events occur, eliminating the need to poll the API for updates. These notifications are sent as HTTP POST requests to a URL you specify.

Configuring Webhooks

Setting Up Your Webhook URL

To configure your webhook endpoint in the StableMint platform:

1. Log in to the StableMint customer dashboard at dashboard.stablemint.io
2. Navigate to the Developer Hub section and go to the Webhook Handlers tab
3. Click on the Create Webhook button (note that there can only be one webhook endpoint per Event Type, therefore the button might be grayd out if there is no available endpoints)
4. Enter the URL where you want to receive webhook notifications

Your webhook endpoint should be a dedicated URL that is capable of processing incoming webhook events securely and reliably.

Best Practices for Webhook URLs

• Use HTTPS for your webhook endpoint to ensure secure data transmission
• Ensure your webhook endpoint is publicly accessible
• Consider using a dedicated endpoint specifically for handling StableMint webhooks

Handling Webhook Notifications

Response Requirements

When StableMint sends a webhook to your endpoint, your server must respond with any 2xx status code (e.g., 200, 201, 202, etc.) to acknowledge receipt. This response informs our system that the webhook was successfully delivered and processed.

Retry Mechanism

If your endpoint fails to respond with a 2xx status code, StableMint will reattempt to send the notification following a structured retry policy:

Attempt	Delay Before Retry
1st retry	5 minutes
2nd retry	10 minutes
3rd retry	30 minutes
4th retry	60 minutes
5th retry	90 minutes

After the 5th unsuccessful retry attempt, the webhook delivery will be marked as failed, and no further attempts will be made.

Webhook Payload

Webhook notifications include information about the payment initiation or withdrawal request. The exact payload structure will depend on the event type, but will typically include:

{
  "sessionId": "string",
  "amount": 0,
  "currency": "string",
  "paymentMethod": "string",
  "paymentReference": "string",
  "notificationType": "string",
  "userId": "string",
  "userCountryCode": "string",
  "idempotencyKey": "string",
  "websiteReference": "string",
  "customFields": null,
  "accountBicCode": "string",
  "accountName": "string",
  "accountAddress": "string",
  "accountIban": "string",
  "status": "string"
}

Further Considerations

1. Due to the nature of HTTP requests, you must implement idempotency logic to handle potential duplicate webhook notifications
2. Process webhooks asynchronously without long-running processes to avoid timeouts

Example Events

StableMint sends webhooks for various events, including but not limited to:

• InwardPaymentAccepted: A payment has been initiated
• InwardPaymentFailed: A payment has been successfully completed
• OutwardPaymentSent: A payment has failed
• OutwardPaymentFailed: A withdrawal has been initiated

For any questions or assistance with webhooks, please contact us at [email protected].