Untuk developer

Webhook ke sistem Anda

Wavely mengirim webhook HTTP POST ke sistem Anda setiap kali ada perubahan di bisnis milik aplikasi Anda.

Kejadian yang bisa Anda terima

Webhook mengirim kabar ke sistem Anda lewat HTTP POST setiap kali sesuatu berubah di bisnis milik aplikasi Anda. Ada 33 jenis kejadian:

  • kontak: contact.created, contact.updated, contact.deleted, contact.opted_out, contact.opted_in
  • perusahaan: company.created, company.updated, company.deleted
  • percakapan: conversation.created, conversation.closed
  • pesan: message.created, message.status_updated, message.edited, message.deleted
  • kanal: channel.updated
  • tim: division.created, division.updated, division.deleted, division.members_updated
  • agen: agent.created, agent.updated, agent.deleted
  • cabang: branch.created, branch.updated, branch.deleted
  • produk: product.created, product.updated, product.deleted
  • penawaran: quotation.created, quotation.sent, quotation.accepted
  • bisnis: organization.updated, organization.deleted

Setiap kiriman berisi id, type, version, timestamp, organization_id, dan data.

Mendaftarkan endpoint

Butuh kunci rahasia dengan scope webhooks:manage. Rute webhook tidak memakai header Wavely-Organization.

curl -X POST https://HOST-WAVELY/platform/v1/webhook-endpoints \
  -H "Authorization: Bearer wvsk_..." \
  -H "Idempotency-Key: 6f1c0d52-0b0e-4c7e-9d1a-3c2a1f6b7e10" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://app.contoh.id/wavely","event_types":["message.created","conversation.closed"]}'

event_types yang kosong berarti semua jenis. URL harus mengarah ke alamat publik. Setiap aplikasi boleh punya sampai 20 endpoint. Untuk mengambil rahasia penandatanganan, panggil GET /webhook-endpoints/{id}/secret. Panggil POST /webhook-endpoints/{id}/test untuk mengirim kejadian webhook.test.

Memeriksa tanda tangan

Wavely menandatangani tiap kiriman mengikuti spesifikasi Standard Webhooks. Header webhook-id, webhook-timestamp, dan webhook-signature menyertai kiriman. Kuncinya adalah byte hasil decode base64 dari rahasia whsec_.... Tanda tangan adalah HMAC-SHA256 dari id.timestamp.isi, berbentuk v1, diikuti tanda tangan base64.

import base64, hashlib, hmac

def valid(secret, msg_id, ts, body, header):
    raw = secret.removeprefix("whsec_")
    key = base64.b64decode(raw + "=" * (-len(raw) % 4))
    signed = f"{msg_id}.{ts}.".encode() + body
    mac = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(mac, p[3:]) for p in header.split() if p.startswith("v1,"))

Jawab dengan status 2xx untuk menandai berhasil. Pengiriman sekurang-kurangnya sekali dan urutannya tidak dijamin, jadi simpan webhook-id dan abaikan yang sudah diproses. Kiriman yang gagal dicoba ulang sampai sepuluh kali dalam kira-kira tiga hari. Endpoint yang gagal terus selama 72 jam dinonaktifkan otomatis. Setelah memperbaikinya, Anda bisa mencoba ulang satu pengiriman atau memutar ulang kejadian dalam rentang waktu tertentu.