Kontrak webhook B2B harus lebih dari sekedar URL dan payload. Dalam pengantar ini, kami langsung menanggapi inti permasalahan: bagaimana mendokumentasikan schema, menjamin otentikasi dan idempotensi, serta menjaga konsistensi saat retry dan observability aktif. Artikel ini menjelaskan langkah praktis untuk menyusun kontrak yang kredibel sehingga pemanggil dan penerima tetap sinkron.

1. Mendokumentasikan Schema Request/Response

Kontrak yang jelas dimulai dari dokumentasi schema. Gunakan JSON Schema atau OpenAPI untuk mengikat struktur payload, tipe data, dan validasi awal. Contoh minimal untuk event pengiriman pesanan:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "order.created",
  "type": "object",
  "properties": {
    "order_id": {"type": "string"},
    "total_amount": {"type": "number", "minimum": 0},
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku": {"type": "string"},
          "quantity": {"type": "integer", "minimum": 1}
        },
        "required": ["sku", "quantity"]
      },
      "minItems": 1
    }
  },
  "required": ["order_id", "total_amount", "items"]
}

Dokumentasi harus mencantumkan validasi tambahan seperti format tanggal, nilai enum, serta perbedaan antara bidang wajib dan optional. Sertakan juga contoh respon sukses dan error, sehingga konsumen tahu apa yang mereka dapatkan dan bagaimana menangani status HTTP yang berbeda.

2. Otentikasi dan Integritas Data

Sistem webhook B2B mesti turun tangan dengan otentikasi kuat: mutual TLS (mTLS) atau signature berbasis HMAC. Pada mTLS, kedua sisi saling memverifikasi sertifikat; ini cocok jika kedua belah pihak dapat mengelola CA internal. Signature cocok jika konsumen tidak bisa menyediakan sertifikat publik yang valid. Contoh header signature:

POST /webhook/order HTTP/1.1
Host: consumer.example.org
X-Signature: sha256=7f9c2ba4e88f827d616045507605853e
Content-Type: application/json

{ ... payload ... }

Untuk signature, kontrak harus menetapkan algoritma hash, secret rotate policy, dan bagaimana penerima menghitung ulang signature (misal raw body + timestamp). Sertakan pula batas waktu (tolerance) untuk menghindari replay attack.

3. Menjamin Idempotensi Payload

Webhook B2B rentan duplikasi karena retry. Kontrak harus menyertakan mekanisme idempoten seperti field event_id atau payload_id yang unik per event. Penerima wajib menyimpan event yang sudah diproses sampai batas waktu tertentu dan menolak duplikat dengan log yang jelas.

Contoh payload dengan header auth dan idempotensi:

POST /webhook/order HTTP/1.1
Host: consumer.example.org
Authorization: Signature keyId="partner-123",algorithm="hmac-sha256",signature="abc123",
X-Event-Id: order.created:20241015:9834
Content-Type: application/json

{"order_id":"ORD-20241015-01","total_amount":1234.5,"items":[{"sku":"SKU-111","quantity":2}]}

Penerima harus mengembalikan HTTP 202 jika payload diterima untuk diproses secara asynchronous dan menyimpan X-Event-Id agar duplikat diabaikan.

4. Strategi Retry dan Backoff

Kontrak juga perlu menegaskan bagaimana konsumen mengulangi pengiriman bila penerima tidak merespons. Seringnya praktik adalah eksponensial backoff dengan jitter dan failure threshold. Misalnya, ulangi maksimal 5 kali dengan interval awal 2 detik dan jeda ganda setiap kali lalu tambahkan jitter ±20%. Kesepakatan ini meminimalisir beban pada sistem penerima sekaligus memberikan waktu pemulihan.

Catat bahwa penerima harus mengembalikan status 2xx hanya setelah memvalidasi signature dan menyimpan event. Bila terjadi error sementara (500-an), kembalikan 503 sehingga konsumen tahu retry berpotensi diperlukan. Hindari 200 karena akan menghentikan retry walau proses internal gagal.

5. Observability: Logging dan Alerting

Observability penting untuk mendeteksi mismatch kontrak. Penerima harus mencatat metadata seperti event_id, timestamp, status signature, waktu proses, dan status penyimpanan. Gunakan correlation ID yang sama di sistem penerima agar log dapat ditelusuri dari konsumen ke handler internal.

Selain logging, definisikan metrik untuk alerting: misalnya error rate > 2% dalam window 5 menit, event latency > SLA, dan signature mismatch. Ini memberi tim lebih cepat respons saat kontrak tidak lagi dipenuhi.

6. Versi dan Penanganan Breaking Change

Perubahan schema harus disertai strategi versi agar kedua pihak tetap sinkron. Pilihlah salah satu pendekatan:

  • Versioned endpoint: /webhook/v1/order dan /webhook/v2/order. Cocok bila breaking change signifikan.
  • Header versioning: X-Contract-Version: 2. Lebih fleksibel, tetapi memerlukan validasi header di sisi penerima.

Proses perubahan ideal mengikuti: pengumuman versi baru -> transisi bersama (dual write) -> tinggalkan versi lama setelah periode stabil. Jangan lupa dokumentasikan fallback: apa yang terjadi bila konsumen masih memanggil versi lama (tanggapan 404/410 atau informasi error terstruktur).

7. Checklist Validasi Kontrak

  • Schema request dan response terdokumentasi dengan JSON Schema/OpenAPI.
  • Aturan otentikasi (mTLS/signature) dijelaskan lengkap termasuk header dan rotasi secret.
  • Field unik untuk idempotensi tercantum dan penerima wajib menyimpan riwayat.
  • Retry/backoff distandarisasi lengkap dengan respons status HTTP yang konsisten.
  • Observability terukur dengan log metadata dan metrik error/latensi.
  • Versi atau breaking change dikelola dengan endpoint/header versi dan masa transisi.

Checklist ini bisa dipelajari bersama tim saat review kontrak, sehingga tidak ada aspek kritis yang terlewat.

Kesimpulan

Mendesain kontrak webhook B2B berarti menetapkan ekspektasi detail antara pemanggil dan penerima. Dengan schema terdokumentasi, otentikasi aman, idempotensi terjamin, retry konsisten, observability aktif, dan pengelolaan versi yang disiplin, integrasi menjadi kredibel dan tahan gangguan. Gunakan checklist sebagai pengingat setiap integrasi baru atau perubahan kontrak.