Real-time Events
Outbound Webhooks
SyncFlo uses webhooks to notify your application in real-time when events occur within your integration. Register a secure endpoint to start receiving data.
Webhook Architecture
SyncFlo sends signed
POST
requests with JSON payloads to your registered URL. Your server should respond with a200 OKstatus to acknowledge receipt.Setup Process
1
Create Endpoint
Host a public HTTPS URL capable of receiving POST requests.
2
Register via API
POST to /api/webhooks/endpoints with your URL and events.
3
Select Events
Choose the event types your application needs to monitor.
4
Verify Secret
Store the whsec_... signing secret for signature validation.
Webhook Endpoints
POST
/api/webhooks/endpointsRegister a new webhook endpoint.
Body: { url, events, description }GET
/api/webhooks/endpointsList all registered webhook endpoints.
DELETE
/api/webhooks/endpoints?id=uuidRemove a webhook endpoint.
Signature Verification
All webhooks are signed with HMAC-SHA256 via the X-SyncFlo-Signature header. Verify using your endpoint's whsec_... signing secret.
X-SyncFlo-Event
Identifies the type of event being delivered.
X-SyncFlo-Signature
HMAC SHA256 signature generated with your secret.
X-SyncFlo-Timestamp
Unix timestamp to prevent replay attacks.
Verification Logic (Node.js)
const crypto = require('crypto');
function verifyWebhook(secret, payload, signature) {
const hmac = crypto.createHmac('sha256', secret);
const digest = Buffer.from(
hmac.update(payload).digest('hex'),
'utf8'
);
const sig = Buffer.from(signature, 'utf8');
return crypto.timingSafeEqual(digest, sig);
}Event Catalog
| Event | Triggered When |
|---|---|
message.received | A WhatsApp message arrives |
message.sent | A message is sent via the API or agent |
lead.created | A new lead is created |
lead.deleted | A lead is deleted via the API |
order.created | An order is created |
order.status_changed | An order's status is updated |
agent.config_changed | An agent's configuration is modified |
knowledge.updated | Knowledge base content is uploaded/deleted |
campaign.queued | A campaign is queued for delivery |
Delivery & Retries
Synchronous acknowledgment is required. If a delivery attempt fails, SyncFlo will retry up to 3 attempts with exponential backoff (1s → 2s → 4s).