In Progress — Webhooks are currently under development. This page documents the planned functionality. For now, use the Payment Status and Check Deposit endpoints to poll for updates.Want early access? Contact us at mitesh@stableyard.fi Webhook Overview Stableyard will send real-time notifications to your server when important events occur. Configure a webhook endpoint to receive these updates automatically instead of polling.
Event Types Event Description payment.createdPayment order created payment.pendingPayment awaiting confirmation payment.completedPayment successfully settled payment.failedPayment failed account.createdMoney Account registered vault.createdVault deployed vault.fundedDeposit received in vault kyc.completedKYC verification passed kyc.failedKYC verification failed
Webhook Payload All webhooks follow this structure:
{ "event" : "payment.completed" , "timestamp" : "2024-01-15T10:30:00Z" , "data" : { // Event-specific data }, "signature" : "sha256=abc123..." }
Event Payloads payment.completed { "event" : "payment.completed" , "timestamp" : "2024-01-15T10:30:00Z" , "data" : { "transactionId" : "tx_abc123" , "quoteId" : "quote_xyz789" , "payerId" : "user_sender" , "payerAddress" : "sender@partner" , "recipientId" : "user_recipient" , "recipientAddress" : "recipient@partner" , "amount" : "100.00" , "token" : "USDC" , "chain" : "Base" , "status" : "completed" , "settledAt" : "2024-01-15T10:30:00Z" } }
account.created { "event" : "account.created" , "timestamp" : "2024-01-15T10:30:00Z" , "data" : { "userId" : "user_abc123" , "username" : "alice" , "paymentAddress" : "alice@partner" , "createdAt" : "2024-01-15T10:30:00Z" } }
vault.funded { "event" : "vault.funded" , "timestamp" : "2024-01-15T10:30:00Z" , "data" : { "userId" : "user_abc123" , "vaultAddress" : "0x..." , "amount" : "500.00" , "token" : "USDC" , "chain" : "Ethereum" , "txHash" : "0x..." , "sourceAddress" : "0x..." } }
kyc.completed { "event" : "kyc.completed" , "timestamp" : "2024-01-15T10:30:00Z" , "data" : { "userId" : "user_abc123" , "verificationLevel" : "full" , "completedAt" : "2024-01-15T10:30:00Z" } }
Signature Verification Always verify webhook signatures to ensure authenticity:
import crypto from 'crypto' ; function verifyWebhook ( payload : string , signature : string , secret : string ) : boolean { const expectedSignature = crypto . createHmac ( 'sha256' , secret ) . update ( payload ) . digest ( 'hex' ); return `sha256= ${ expectedSignature } ` === signature ; } // In your webhook handler app . post ( '/webhook' , ( req , res ) => { const signature = req . headers [ 'x-stableyard-signature' ]; const isValid = verifyWebhook ( JSON . stringify ( req . body ), signature , process . env . WEBHOOK_SECRET ); if ( ! isValid ) { return res . status ( 401 ). send ( 'Invalid signature' ); } // Process webhook const { event , data } = req . body ; // ... res . status ( 200 ). send ( 'OK' ); });
Retry Policy Attempt Delay 1 Immediate 2 1 minute 3 5 minutes 4 30 minutes 5 2 hours
After 5 failed attempts, the webhook is marked as failed.
Best Practices
Return 200 Quickly Acknowledge receipt immediately, process async
Verify Signatures Always validate webhook authenticity
Handle Idempotency Events may be delivered multiple times
Log Everything Store payloads for debugging
Configuring Webhooks Coming Soon — Webhook configuration will be available via API and dashboard. Register your interest to be notified when webhooks launch.
When available, you’ll be able to configure:
Endpoint URL: Your HTTPS endpointEvents: Which events to receiveSecret: Shared secret for signature verification
