Developers

Webhooks

Copy page

Webhooks

Webhooks memungkinkan Anda menerima notifikasi real-time saat event terjadi di kirim.dev, seperti pesan masuk atau status update.

Membuat Webhook

1. Buka Webhooks di sidebar
2. Klik Create Webhook
3. Isi form:
   • URL: Endpoint yang akan menerima webhook
   • Events: Pilih events yang ingin diterima
   • Secret (opsional): Secret untuk signature verification
4. Klik Create
5. Verifikasi webhook (lihat bagian Verification)

Events

Message Events

Event	Deskripsi
message.received	Pesan baru diterima
message.sent	Pesan berhasil dikirim
message.delivered	Pesan terdelivered ke device
message.read	Pesan dibaca oleh penerima
message.failed	Pengiriman pesan gagal

Contact Events

Event	Deskripsi
contact.created	Kontak baru dibuat
contact.updated	Kontak diupdate
contact.deleted	Kontak dihapus

Conversation Events

Event	Deskripsi
conversation.opened	Percakapan baru dimulai
conversation.resolved	Percakapan di-resolve
conversation.reopened	Percakapan dibuka kembali

Broadcast Events

Event	Deskripsi
broadcast.started	Broadcast mulai berjalan
broadcast.completed	Broadcast selesai

Webhook Payload

Message Received

Code
 
{
  "event": "message.received",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "+628123456789",
    "to": "+628111222333",
    "device_id": 1,
    "type": "text",
    "content": "Halo, saya mau tanya produk",
    "contact": {
      "id": 123,
      "name": "John Doe",
      "phone": "+628123456789"
    },
    "conversation_id": 456,
    "referral": null
  },
  "workspace_id": 1
}

Message Status Update

Code
 
{
  "event": "message.delivered",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "message_id": "wamid.xxx",
    "status": "delivered",
    "recipient": "+628123456789"
  },
  "workspace_id": 1
}

Verification

Saat membuat webhook, kirim.dev akan mengirim verification request:

Code
 
GET https://your-webhook-url?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE_STRING

Response yang diharapkan:

• Status: 200
• Body: nilai hub.challenge

Signature Verification

Jika Anda set secret, setiap webhook request akan menyertakan signature di header:

Code
 
X-Webhook-Signature: sha256=xxxxxxxxxxxxxxxx

Verify Signature (Node.js)

Code
 
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + 
    crypto.createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Verify Signature (PHP)

Code
 
function verifySignature($payload, $signature, $secret) {
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expectedSignature, $signature);
}

Verify Signature (Python)

Code
 
import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Retry Policy

Jika webhook gagal (non-2xx response), kirim.dev akan retry:

Attempt	Delay
1	Immediate
2	1 menit
3	5 menit
4	30 menit
5	2 jam

Setelah 5 kali gagal, webhook akan di-disable otomatis.

Mengelola Webhooks

Edit Webhook

1. Klik webhook di list
2. Update URL atau events
3. Klik Save

Test Webhook

1. Klik Test pada webhook
2. Pilih event type
3. Kirim test payload
4. Lihat response

Disable/Enable

Toggle status webhook untuk sementara menonaktifkan tanpa menghapus.

Delete Webhook

1. Klik icon Delete
2. Konfirmasi penghapusan

Best Practices

1. Respond Quickly

Return 200 OK secepat mungkin, proses data secara async:

Code
 
app.post('/webhook', (req, res) => {
  // Respond immediately
  res.status(200).send('OK');
  
  // Process async
  processWebhook(req.body);
});

2. Handle Duplicates

Webhook bisa dikirim lebih dari sekali. Gunakan message_id untuk dedupe:

Code
 
async function processWebhook(data) {
  const exists = await db.findOne({ message_id: data.message_id });
  if (exists) return; // Already processed
  
  // Process...
}

3. Verify Signature

Selalu verify signature untuk memastikan request berasal dari kirim.dev.

4. Use HTTPS

Webhook URL harus menggunakan HTTPS untuk keamanan.

5. Log Everything

Log semua webhook untuk debugging:

• Timestamp
• Event type
• Payload
• Response

Troubleshooting

Webhook tidak diterima

1. Cek URL accessible dari internet
2. Cek firewall/security rules
3. Pastikan respond dengan 2xx status
4. Lihat webhook logs di dashboard

Signature verification gagal

1. Pastikan secret di code sama dengan di dashboard
2. Gunakan raw body untuk verification, bukan parsed JSON
3. Cek encoding (harus UTF-8)