Setup Webhook & Integrasi Eksternal

Webhook memungkinkan sistem eksternal Anda menerima event real-time dari Velora — pesan masuk, perubahan status, atau event CRM. Dokumen ini menjelaskan cara mengonfigurasinya.

Konfigurasi URL Webhook

Buka Settings → Webhooks → Add Endpoint.

• Masukkan URL publik HTTPS (mis. https://api.tokokopi.id/velora/webhook).
• Pilih event yang ingin dilanggan.
• Simpan — Velora mengirim verify token ke URL untuk validasi kepemilikan.
• Endpoint aktif setelah server Anda merespons challenge dengan benar.

Tipe Event yang Tersedia

Event	Dipicu Saat
message.received	Pesan masuk dari pelanggan
message.delivered	Pesan terkirim ke perangkat
message.read	Pesan dibaca pelanggan
message.failed	Pengiriman gagal
contact.created	Kontak baru terbentuk
broadcast.completed	Broadcast selesai diproses

Contoh Payload

Berikut contoh payload untuk event message.received:

{
  "event": "message.received",
  "timestamp": "2026-07-19T08:42:13.482Z",
  "data": {
    "messageId": "msg_01H8X9...",
    "channel": "whatsapp",
    "from": "+6281234567890",
    "contactId": "ctc_abc123",
    "type": "text",
    "text": { "body": "Halo, apakah stok kopi toraja masih ada?" }
  }
}

Verifikasi Signature

Setiap request disertai header X-Velora-Signature berupa HMAC-SHA256 dari body menggunakan secret webhook Anda. Verifikasi di server:

import crypto from "node:crypto";

function verify(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Best Practices

• Balas 200 cepat: proses event asynchronously agar Velora tidak retry.
• Idempotency: gunakan messageId untuk deduplikasi.
• Retry: Velora retry 5x dengan backoff eksponensial bila endpoint gagal.

Dengan webhook yang andal, Velora bisa menjadi tulang punggung automasi lintas-sistem Anda.