Receiving Webhooks

Webhooks are a crucial part of the Stable Mint 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 Stable Mint platform:

1. Log in to the Stable Mint 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 grayed 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 Stable Mint webhooks

Webhook Security

Signature Verification

All webhooks sent by Stable Mint include signature headers that allow you to verify the authenticity of the webhook. This ensures that the webhook was indeed sent by Stable Mint and that the payload has not been tampered with.

Each webhook request includes these headers:

StableMint-Timestamp: <ISO 8601 TIMESTAMP>
StableMint-Signature: <BASE64 ENCODED RSA-SHA256 SIGNATURE>

Verifying the Signature

To verify the webhook signature:

1. Extract the StableMint-Timestamp and StableMint-Signature headers from the request
2. Construct the signature payload by concatenating: <TIMESTAMP>,<REQUEST_BODY>
   • <TIMESTAMP> is the value from the StableMint-Timestamp header
   • <REQUEST_BODY> is the raw JSON request body
3. Use Stable Mint's public RSA key to verify the signature against the constructed payload
4. The signature uses RSA-SHA256 with PKCS1 padding

Example signature verification (pseudocode):

payload = timestamp + "," + requestBody
signature = base64Decode(signatureHeader)
isValid = rsaVerify(payload, signature, publicKey, SHA256, PKCS1)

Public Keys for Signature Verification

Use the following public keys to verify webhook signatures:

Sandbox

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqeqrieRg9f1hWqw6Y9I6
fh0T+R22pWIP4CkYmgaKSXmZ9jBVtWaoVeeLr3JdLIWjM4P5PSMx2CReygegKzxf
tOnh5uXXeKbQUtYqGWArRZyFb3p0sasG/U43AGjBqn4iRPejuAy8e3hYQMqKtFuO
TyXSk9g+O9ZzSn6xuJumY2tnNwJtXrNPrJVVB6zyckcMeBAP99QeMORsCTWBRE6k
sqgPmGxUSOmK5IahDtyMNg7bEpB5ODA7+K232gRCadzQwhJC5MiYtbucjziJhbZ4
yrMNVBM5qs7C9Kpx2DwXfuA3/ynQ2Xh3IQp6CC+UEbjCasCDdquwt8lgew7YbOpG
3QIDAQAB
-----END PUBLIC KEY-----

Production

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAj9nFL5jAcQS5bbTJHUP3
msnNQCax+SSEXC3am+GddydFli3IUXeqIJQqrmwJgfVRRseSLCaDH1+45fe0XxdV
hDn3jtux+XZTEvGwtadmT1bT4TGrfiLYMo8P4Bbp1Vb3AUl3zM6mV8ytmAIop+au
k80FLZpzSYHk3i4QntzY1+/Bm0AcYL1cDU4k9ukb6tT9vqz20PvcFAhrr2RIt6GQ
lfxs5Ft0Kp9mZ+JxCj/vvYCLjZ8B3gH1V0UljzhAc/QizJw/y75FEYC/qeAifoyf
piwMcwuu634Vx6AKDw4tVA6YtgLb8Kwm6aIki8YfAkGRVawsm5JlzmZXF1c3xI9w
EwIDAQAB
-----END PUBLIC KEY-----

WARNING

Always verify the webhook signature before processing the webhook payload to ensure the request is legitimate.

Handling Webhook Notifications

Response Requirements

When Stable Mint 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, Stable Mint 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

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

Deposit Events

• partner.customer.deposit.created: A new deposit request has been created
• partner.customer.deposit.submitted: A deposit has been submitted to the payment processor
• partner.customer.deposit.reconciled: A deposit has been successfully reconciled with the bank
• partner.customer.deposit.accepted: A deposit has been accepted and funds are available
• partner.customer.deposit.failed: A deposit has failed to process

Withdrawal Events

• partner.customer.withdrawal.requested: A withdrawal request has been created
• partner.customer.withdrawal.accepted: A withdrawal has been accepted for processing
• partner.customer.withdrawal.failed: A withdrawal has failed to process
• partner.customer.withdrawal.sent: A withdrawal has been successfully sent to the beneficiary

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