Webhooks

Overview

Webhooks let your platform react to treasury events without polling. Configure endpoints in Settings → Webhooks. The dashboard now exposes endpoint filtering, delivery inspection, manual replay, and secret rotation so operators do not need to leave the app to manage delivery health.

Event Types

These are the current public event names emitted by the checkout, payout, and refund flows.

Webhook Payload

Deliveries include a JSON body and signature headers.

Headers

Example Payload

{
  "event": "payout.executed",
  "data": {
    "payout_id": "6f2f0ac5-4f50-4e96-b412-4f534f1c85c6",
    "external_id": "tr_123",
    "status": "completed",
    "occurred_at": "2026-03-12T10:29:30Z"
  }
}

Verifying Signatures

Always verify the signature before processing the payload.

import Soledgic from '@soledgic/sdk';

const soledgic = new Soledgic({
  apiKey: process.env.SOLEDGIC_API_KEY!,
  baseUrl: 'https://api.soledgic.com/v1',
  apiVersion: '2026-03-01',
});

const rawBody = await request.text();
const signature = request.headers.get('x-soledgic-signature') || '';

const isValid = await soledgic.webhooks.verifySignature(
  rawBody,
  signature,
  process.env.SOLEDGIC_WEBHOOK_SECRET!,
);

if (!isValid) {
  throw new Error('Invalid webhook signature');
}

Retry Policy

• Up to 5 retry attempts for non-2xx responses
• Exponential backoff between attempts, capped at 4 hours
• HTTP 429 responses are slowed down to at least 5 minutes before retry
• Failed deliveries stay visible in webhook delivery history, including payload and response body
• Operators can manually replay exhausted deliveries from Settings → Webhooks

Operations

The webhook settings screen is designed for production operations, not just initial setup.

• Filter delivery history by endpoint
• Inspect payloads, headers, attempts, and downstream response bodies
• Replay stuck or exhausted deliveries after downstream fixes
• Rotate endpoint secrets and keep the previous secret valid during the grace period

Best Practices