Webhooks — eventy z Unifyo do tvojho backendu

Čo sú webhooks

Real-time POST do tvojho endpointu pri každom evente v Unifyo:

• contact.created — nový CRM kontakt
• deal.stage_changed — preplánovaný deal
• deal.won — deal vyhraný
• campaign.sent — marketing kampaň dokončená
• campaign.reply — odpoveď na kampaň (do 7 dní)
• msg.inbound — nová WhatsApp správa
• subscription.changed — zmena plánu

Vytvorenie

1. Settings → Integrácie → Webhooks
2. + Nový webhook
3. Endpoint URL (HTTPS only) + výber eventov + meno
4. Klik Vytvoriť → server vráti secret (zobrazí sa raz, ulož si)

Payload

json
{
  "event": "contact.created",
  "data": {
    "id": "cmoxxx",
    "name": "Peter Novák",
    "email": "peter@example.com",
    "phone": "+421 950 312 345"
  },
  "occurredAt": "2026-05-08T10:23:00.000Z"
}

Headers

Content-Type: application/json
User-Agent: Unifyo-Webhooks/1.0
X-Unifyo-Signature: t=1715164980,v1=abc123...
X-Unifyo-Event: contact.created
X-Unifyo-Delivery: cmoyyy

Verifikácia podpisu

javascript
const crypto = require('crypto');
function verifyWebhook(rawBody, signatureHeader, secret) {
  const m = signatureHeader.match(/^t=(\d+),v1=([0-9a-f]+)$/);
  if (!m) return false;
  const [_, ts, sig] = m;
// Reject signatures older than 5 minutes (replay protection).
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = crypto
    .createHmac('sha256', secret)
    .update(${ts}.${rawBody})
    .digest('hex');
// Constant-time compare.
  return crypto.timingSafeEqual(
    Buffer.from(sig, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

Retry policy

Pri non-2xx response retry s exponential backoff:

| Pokus | Po koľkých minútach |
|---|---|
| 1 | hneď |
| 2 | +1 min |
| 3 | +5 min |
| 4 | +30 min |
| 5 | +2 hod |
| 6 | +12 hod |

Po 5 zlyhaniach subscription sa auto-pozastaví a my ti pošleme email.

Best practice

• Vráť 200 OK rýchlo (do 10s) — Unifyo má 10s timeout
• Spracuj payload asynchrónne v queue, nie synchronne
• Idempotency: použi X-Unifyo-Delivery ako idempotency key — ten istý delivery sa môže poslať viackrát pri retry
• Signature mandatory: nikdy nedôveruj payload-u bez verifikácie