Webhooks

Paths are relative to https://fliok.com/api/v1. Each endpoint names the scope and the lowest key role it needs; a key without them gets 403 (see Authentication).

Register a webhook URL and Fliok POSTs to it whenever an event occurs. 43 events are emitted today. Every payload is signed with HMAC-SHA256 using your endpoint secret, and every body has the same shape: { id, event, createdAt, data } — createdAt is when the event happened, the same on every retry. Non-2xx responses are retried with backoff (12 attempts over about 17 hours), and an endpoint that keeps failing is disabled automatically.

The invoice.*, quotation.*, booking.* and review.received events come from Invoices and Bookings, and fire for a workspace that has switched them on. Each is written down in the same step as the fact itself, so it is sent once whoever caused it — a team member, your payment gateway, or the customer on their own page — a few seconds later. Every amount comes twice: in minor units (paise for INR) for arithmetic, and as the text printed on the document. Registering a webhook needs an admin key for these money events (a no-code key with webhooks:manage can subscribe to bookings and reviews, never to invoices or quotations), so they never reach an agent-role key.

• De-duplicate on the event id. Delivery is at least once: a retry, or a redelivery from the dashboard, carries the same x-webhook-id (and body id). Store the ids you have handled and skip a repeat.
• A customer may have no phone number. WhatsApp lets people use a username, and then shares no number for them. Their phone is wa:<user id> instead of digits, and events that name a contact also carry userId (their WhatsApp user id) and username whenever WhatsApp sent them — for customers with a number too. To answer, pass that phone to POST /send as to exactly as you received it, or send recipient: userId. Don’t treat phone as digits.
• Reject stale requests. Refuse a delivery whose x-webhook-timestamp (unix seconds, when this attempt was signed) is more than five minutes from your clock, so a captured request can’t be replayed later.
• Rotate without downtime. POST /webhooks/{id}/rotate (or Rotate secret on the API keys page) returns a new secret once. For the next 24 hours x-webhook-signature carries two signatures, sha256=<new>,sha256=<old>: accept the delivery when any one matches, switch your server to the new secret, and the old one stops after the 24 hours.
• See what was sent. The API keys page keeps every attempt for 7 days — status, timing, error and the payload — and can send any of them again.

Choose what you receive with the events array when you register or PATCH an endpoint — for example ["message.received","message.failed"], or a single event — what a no-code tool subscribing one URL per automation sends. Leave both out (the default) to receive every event, including ones added later. The x-webhook-event header always names the event. GET /webhooks/samples/{event} shows what a delivery of an event looks like before one has happened. Using Zapier, Make or Pabbly? See Zapier, Make and Pabbly Connect.

Hash the raw body with your endpoint’s secret and compare. The example is Node.js with Express; the steps are the same in any language.

const crypto = require('crypto');

// Headers on every delivery:
//   x-webhook-id, x-webhook-event, x-webhook-timestamp, x-webhook-signature
// The signature is HMAC-SHA256 over `${timestamp}.${rawBody}`, hex, prefixed "sha256=".
// For 24 hours after a secret is rotated the header carries two, comma-separated:
// "sha256=<new>,sha256=<old>" — accept the delivery when any one matches.
// You MUST hash the RAW body — re-serialising the parsed JSON will not match.

function verifyWebhook(rawBody, headers, secret) {
  const ts = headers['x-webhook-timestamp'];
  // Refuse anything signed more than 5 minutes away from now (a replayed request).
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)          // the whsec_… shown once on creation
    .update(ts + '.' + rawBody)
    .digest('hex');
  return (headers['x-webhook-signature'] || '').split(',').some((got) =>
    expected.length === got.trim().length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got.trim())));
}

// In your Express route (note express.raw, not express.json):
app.post('/webhooks/fliok', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyWebhook(req.body.toString(), req.headers, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { id, event, createdAt, data } = JSON.parse(req.body.toString());
  // Delivered at least once: skip an id you have already handled.
  // event is one of message.received, message.status, message.failed, template.approved, template.rejected, template.category_changed, contact.created, contact.updated, contact.deleted, conversation.opened, conversation.closed, conversation.rated, flow.completed, call.missed, order.cod_response, order.event, broadcast.completed, lead.created, lead.recaptured, form.submitted, lead.stage_changed, lead.assigned, task.created, task.completed, instagram.message.received, instagram.comment.received, instagram.post.published, payment.paid, invoice.issued, invoice.updated, invoice.payment_recorded, invoice.paid, invoice.payment_voided, invoice.cancelled, quotation.accepted, quotation.declined, booking.created, booking.rescheduled, booking.cancelled, booking.completed, booking.no_show, booking.restored, review.received
  // Always switch on `event` and ignore ones you do not handle — new events may be added.
  res.json({ received: true });
});

The buckets these endpoints use. Burst is how many requests you can make back-to-back from a full bucket; sustained is how fast it refills.

Every limit, the RateLimit-* headers and what to do on a 429: Rate limits.