Webhooks

Stableyard delivers real-time webhook events when key actions occur.

Event Types

EventDescription
payment.createdPayment order created
payment.pendingAwaiting user action
payment.completedPayment settled successfully
payment.failedPayment failed
account.createdMoney Account registered
vault.createdSafe-based vault deployed
kyc.completedKYC verification complete

Webhook Payload

{
  "id": "evt_abc123",
  "type": "payment.completed",
  "createdAt": "2025-01-15T12:00:00Z",
  "data": {
    "paymentId": "pay_xyz789",
    "amount": 99.99,
    "currency": "USD",
    "settleTo": {
      "chain": "base",
      "token": "USDC"
    },
    "metadata": {
      "orderId": "order_123"
    }
  }
}

Verify Signatures

Always verify webhook signatures to ensure the request came from Stableyard.
import { Stableyard } from '@stableyard/sdk'

const stableyard = new Stableyard({
  apiKey: process.env.STABLEYARD_API_KEY!,
  webhookSecret: process.env.STABLEYARD_WEBHOOK_SECRET!
})

app.post('/webhook/stableyard', (req, res) => {
  try {
    const signature = req.headers['x-stableyard-signature'] as string
    const event = stableyard.verifyWebhook(req.body, signature)

    switch (event.type) {
      case 'payment.completed':
        // Fulfill the order
        await fulfillOrder(event.data.metadata.orderId)
        break
      case 'payment.failed':
        // Handle failure
        await handlePaymentFailure(event.data.paymentId)
        break
      // ... handle other events
    }

    res.status(200).send('OK')
  } catch (e) {
    console.error('Webhook verification failed:', e)
    res.status(400).send('Invalid signature')
  }
})

Best Practices

  • Respond quickly: Return a 200 response within 5 seconds. Do async processing after acknowledging.
  • Handle duplicates: Use the event id to deduplicate. Stableyard may retry on failures.
  • Verify signatures: Always verify the x-stableyard-signature header.
  • Log events: Store webhook payloads for debugging and auditing.

Retry Policy

If your endpoint returns a non-2xx status code, Stableyard will retry:
  • 1st retry: 1 minute
  • 2nd retry: 5 minutes
  • 3rd retry: 30 minutes
  • 4th retry: 2 hours
After 4 failed attempts, the webhook is marked as failed.
Need help? Contact us via Telegram or email.