Webhooks

Webhooks let SlaunchX push real-time event notifications to your server, so you don't need to poll the API for status changes. When something happens -- a transfer completes, a wallet is created, a payment settles -- SlaunchX sends an HTTP POST request to your registered endpoint with a JSON payload describing the event.

This is especially useful for:

• Asynchronous workflows -- react to transfer completions without polling.
• Real-time dashboards -- update balances and statuses instantly.
• Audit trails -- record every event as it happens, in order.

---

Setting Up Webhooks

Via the API

Register a webhook endpoint by sending a POST request:

Via the Dashboard

1. Navigate to Settings > Webhooks in your workspace dashboard.
2. Click Add Endpoint.
3. Enter your HTTPS endpoint URL.
4. Select the events you want to subscribe to.
5. Save. SlaunchX will generate a signing secret for you -- store it securely.

:::caution HTTPS required Webhook endpoints must use HTTPS. SlaunchX will not deliver events to plain HTTP URLs in production environments. In sandbox mode, HTTP URLs are allowed for local development. :::

---

Event Types

The following events are available for webhook subscriptions:

Event	Description
transfer.created	A new transfer order has been created
transfer.completed	A transfer has been executed successfully
transfer.failed	A transfer execution failed
payment.created	A payment has been initiated
payment.completed	A payment has settled successfully
payment.failed	A payment failed to settle
wallet.created	A new wallet account has been created
wallet.updated	A wallet's status or configuration changed
wallet.frozen	A wallet has been frozen by an administrator

You can subscribe to individual events or use * to receive all events.

---

Payload Format

Every webhook delivery is an HTTP POST request with a JSON body following this structure:

{
  "id": "evt_8f4a2b3c7d9e",
  "type": "transfer.completed",
  "timestamp": 1709337600000,
  "data": {
    "transferId": "txn_789xyz",
    "sourceWalletId": "w_123",
    "targetWalletId": "w_456",
    "amount": "100.00",
    "currency": "USD",
    "status": "COMPLETED"
  }
}

Payload Fields

Field	Type	Description
id	string	Unique event identifier. Use this for idempotent processing.
type	string	The event type (see Event Types).
timestamp	long	Event timestamp in epoch milliseconds.
data	object	Event-specific payload. The shape depends on the event type.

Delivery Headers

Each webhook request includes these HTTP headers:

Header	Description
Content-Type	Always application/json
X-Webhook-Id	Same as the id field in the payload
X-Webhook-Timestamp	Unix epoch seconds when the request was sent
X-Webhook-Signature	HMAC-SHA256 signature for verification (see below)
User-Agent	SlaunchX-Webhooks/1.0

---

Signature Verification

Every webhook delivery is signed so you can verify it came from SlaunchX and was not tampered with in transit. The signature is computed as:

signature = hex(HMAC-SHA256(webhookSecret, timestamp + "." + rawBody))

Where:

• webhookSecret is the signing secret you received when creating the webhook endpoint.
• timestamp is the value from the X-Webhook-Timestamp header.
• rawBody is the raw HTTP request body (do not parse and re-serialize).

Verification Examples

:::caution Always verify signatures Never process a webhook payload without verifying the signature first. This protects against forged requests. Additionally, check the timestamp to prevent replay attacks -- reject any request where the timestamp is more than 5 minutes old. :::

---

Retry Policy

If your endpoint does not return a 2xx status code within 5 seconds, SlaunchX considers the delivery failed and retries with exponential backoff:

Attempt	Delay After Failure
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	8 hours

After 5 failed retries (6 total attempts), the event is marked as failed. You can manually retry failed deliveries from the dashboard or via the API.

Automatic disabling

If your endpoint fails consistently for 3 consecutive days, SlaunchX will automatically disable the webhook and notify your account administrators via email. Re-enable it from the dashboard once your endpoint is healthy.

---

Best Practices

Respond Quickly

Return a 200 OK response within 5 seconds. Perform any heavy processing asynchronously -- acknowledge receipt first, then process the event in a background job or queue.

Incoming webhook  -->  Verify signature  -->  Return 200  -->  Queue for processing
                                                                      |
                                                               Process event async

Handle Events Idempotently

Webhook deliveries can be retried, which means your endpoint may receive the same event more than once. Use the id field to deduplicate:

1. When you receive an event, check if you have already processed an event with that id.
2. If yes, return 200 and skip processing.
3. If no, process the event and record the id.

Use a Queue

For high-volume integrations, write incoming events to a message queue (e.g., RabbitMQ, SQS, Redis Streams) and process them with a separate worker. This decouples receipt from processing and ensures you always respond within the timeout.

Verify Before Processing

Always verify the webhook signature before processing the payload. Never trust the contents of a webhook request without verification, even if the request appears to come from a known IP.

Monitor Delivery Health

Regularly check the webhook delivery logs in your dashboard. Failed deliveries may indicate endpoint downtime, certificate issues, or network problems that need attention.

---

Testing

Sandbox Environment

The sandbox environment supports full webhook functionality. Use it to test your integration before going live:

1. Create a sandbox webhook -- register your development endpoint (HTTP is allowed in sandbox).
2. Trigger test events -- use the sandbox API to create transfers, wallets, etc. These operations generate real webhook deliveries to your endpoint.
3. Inspect deliveries -- check the delivery log in your sandbox dashboard to see payloads, response codes, and timing.

Send a Test Event

You can send a test event from the dashboard to verify your endpoint is reachable and processing correctly:

1. Go to Settings > Webhooks.
2. Click the endpoint you want to test.
3. Click Send Test Event.
4. Select an event type.
5. SlaunchX sends a sample payload to your endpoint and displays the response.

Local Development

For local development, use a tunneling service to expose your local server to the internet:

Replay events

If you need to re-process an event (e.g., after fixing a bug in your handler), use the dashboard to replay specific deliveries. Each replay generates a new delivery attempt with the original payload.

---

Next Steps

• HMAC Authentication -- Learn how to authenticate API requests with HMAC-SHA256 signatures.
• Error Handling -- Understand the response envelope format and error codes.