Webhooks API Reference
Receive real-time notifications about events in your Waffy integration. Configure secure webhook endpoints to stay updated on payments, contracts, and user activities.
Overview
Webhooks allow your application to receive real-time notifications when events occur in your Waffy integration. Instead of polling our API, webhooks push event data to your endpoints immediately when something happens.
Instant notifications when events occur
HMAC signature verification and HTTPS required
Automatic retries with exponential backoff
PATCHConfigure Webhook
Set up or update your webhook endpoint to receive contract status notifications
Endpoint
Request Body
{
"webhookUrl": "https://example.webhook.com"
}Response (200 OK)
{
"status": 204,
"timestamp": "2026-01-25T12:00:00.000000"
}Note: Success response returns HTTP 204 No Content status with no response body.
Webhook Payload Structure
Example of how webhook events are delivered to your endpoint
Contract Status Update Event
{
"contractId": "697107b674385b2c31672af5",
"status": "PAID",
"referenceId": "txn_9i8h7g6f5e4d"
}Field Descriptions:
contractId- The milestone ID (contract ID of the milestone)status- Current contract status (see status values below)referenceId- Reference ID for the transaction (if applicable)
Contract Status Values
Webhook Security
Verify webhook authenticity with HMAC signatures
Signature Verification
Waffy signs webhook payloads with your webhook secret using HMAC-SHA256. The signature is included in the Waffy-Signature header.
// Node.js example
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
const expectedHeader = `sha256=${expectedSignature}`;
return crypto.timingSafeEqual(
Buffer.from(signature, 'utf8'),
Buffer.from(expectedHeader, 'utf8')
);
}
// Usage in Express.js
app.post('/webhooks/waffy', express.raw({type: 'application/json'}), (req, res) => {
const payload = req.body;
const signature = req.headers['waffy-signature'];
const secret = process.env.WAFFY_WEBHOOK_SECRET;
if (!verifyWebhookSignature(payload, signature, secret)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(payload);
// Process the webhook event
switch (event.status) {
case 'PAID':
handleContractPaid(event);
break;
case 'CASHOUT_IN_PROGRESS':
handleCashoutInProgress(event);
break;
case 'COMPLETED':
handleContractCompleted(event);
break;
// Handle other status types...
}
res.status(200).send('OK');
});Delivery & Retry Policy
Retry Policy
• Webhooks are retried up to 3 times on failure
• Exponential backoff: 1s, 10s, 100s delays
• HTTP 200-299 responses are considered successful
• Timeout after 30 seconds
Best Practices
• Respond with HTTP 200 status code quickly
• Implement idempotency using the event ID
• Always verify the webhook signature
• Process webhooks asynchronously when possible
Common Errors
400 Bad Request - Invalid URL
{
"success": false,
"error": {
"code": "INVALID_WEBHOOK_URL",
"message": "Webhook URL must be HTTPS and publicly accessible",
"details": {
"url": "http://localhost:3000/webhooks",
"requirements": ["HTTPS required", "Must be publicly accessible"]
}
}
}422 Unprocessable Entity - Invalid Events
{
"success": false,
"error": {
"code": "INVALID_EVENTS",
"message": "One or more event types are not supported",
"details": {
"invalid_events": ["payment.refunded", "user.deleted"],
"supported_events": ["payment.completed", "payment.failed", "..."]
}
}
}Webhook Testing Tool
Test your webhook endpoint with sample events
Webhook Guide
Complete guide to implementing webhooks