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:

Log in to the StableMint customer dashboard at dashboard.stablemint.net
Navigate to the Developer Hub section and go to the Webhook Handlers tab
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)
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

Webhook Security

Signature Verification

All webhooks sent by StableMint include signature headers that allow you to verify the authenticity of the webhook. This ensures that the webhook was indeed sent by StableMint 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:

Extract the StableMint-Timestamp and StableMint-Signature headers from the request
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
Use StableMint’s public RSA key to verify the signature against the constructed payload
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:

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

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 Format

Version 2 (Default)

All new webhook integrations use Version 2 by default. In this format, the event payload is wrapped in an envelope containing an eventId for tracking and a data object with the event-specific fields:

{
  "eventId": "evt_abc123def456",
  "data": {
    "eventType": "partner.customer.deposit.created",
    "timestamp": "2025-01-15T10:30:00Z",
    "customerId": "customer_123456789",
    "reference": "DEP123456789",
    "amount": 100.00,
    "currency": "EUR",
    "sessionId": "session_123456789",
    "endToEndId": "E2E123456789",
    "paymentCountryCode": "DE",
    "paymentMethod": "bank_transfer",
    "partnerName": "Partner Company",
    "customerEmail": "customer@example.com",
    "idempotencyKey": "idem_123456789",
    "websiteReference": "order_123456789",
    "customFields": {
      "key1": "value1"
    }
  }
}

Field	Type	Description
`eventId`	string	Unique identifier for this webhook delivery, useful for idempotency checks
`data`	object	The event payload — see Event Types for the full structure of each event

Version 1 (Deprecated)

Deprecation Notice Version 1 is deprecated and will be removed in a future release. All new integrations should use Version 2. If you are currently using Version 1, we recommend migrating to Version 2.

In Version 1, the event payload is sent directly as the request body with the eventId injected as a top-level field alongside the event data:

{
  "eventId": "evt_abc123def456",
  "eventType": "partner.customer.deposit.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "customerId": "customer_123456789",
  "reference": "DEP123456789",
  "amount": 100.00,
  "currency": "EUR",
  "sessionId": "session_123456789",
  "endToEndId": "E2E123456789",
  "paymentCountryCode": "DE",
  "paymentMethod": "bank_transfer",
  "partnerName": "Partner Company",
  "customerEmail": "customer@example.com",
  "idempotencyKey": "idem_123456789",
  "websiteReference": "order_123456789",
  "customFields": {
    "key1": "value1"
  }
}

The key difference is that Version 1 flattens all fields into a single JSON object, whereas Version 2 nests the event data inside the data field.

Further Considerations

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

Event Types

StableMint sends webhooks for various events, including:

Deposit Events

partner.customer.deposit.created: A new deposit request has been created
partner.customer.deposit.initiated: A deposit has been initiated by the customer
partner.customer.deposit.submitted: A deposit has been submitted to the payment processor
partner.customer.deposit.accepted: A deposit has been accepted and reconciled
partner.customer.deposit.failed: A deposit has failed to process
partner.customer.deposit.completed: A deposit has been completed and funds are settled

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.sent: A withdrawal has been successfully sent to the beneficiary
partner.customer.withdrawal.failed: A withdrawal has failed to process

Transaction Events

transaction.status.changed: A transaction status has changed

For detailed payload structures of each event, see the Event Types documentation. For any questions or assistance with webhooks, please contact us at contact@stablemint.io.

Get started

Authentication

Core resources

Accept payments

Send money

Webhooks

Feed

Cross-chain bridge

Overview

Configuring Webhooks

Setting Up Your Webhook URL

Best Practices for Webhook URLs

Webhook Security

Signature Verification

Verifying the Signature

Public Keys for Signature Verification

Handling Webhook Notifications

Response Requirements

Retry Mechanism

Webhook Payload Format

Version 2 (Default)

Version 1 (Deprecated)

Further Considerations

Event Types

Deposit Events

Withdrawal Events

Transaction Events

​Overview

​Configuring Webhooks

​Setting Up Your Webhook URL

​Best Practices for Webhook URLs

​Webhook Security

​Signature Verification

​Verifying the Signature

​Public Keys for Signature Verification

​Handling Webhook Notifications

​Response Requirements

​Retry Mechanism

​Webhook Payload Format

​Version 2 (Default)

​Version 1 (Deprecated)

​Further Considerations

​Event Types

​Deposit Events

​Withdrawal Events

​Transaction Events

Overview

Configuring Webhooks

Setting Up Your Webhook URL

Best Practices for Webhook URLs

Webhook Security

Signature Verification

Verifying the Signature

Public Keys for Signature Verification

Handling Webhook Notifications

Response Requirements

Retry Mechanism

Webhook Payload Format

Version 2 (Default)

Version 1 (Deprecated)

Further Considerations

Event Types

Deposit Events

Withdrawal Events

Transaction Events