Webhooks

Endpoint Webhook

Kelola beberapa URL webhook dengan rahasia per endpoint dan filter peristiwa.

Sistem webhook berbasis endpoint memungkinkan Anda mendaftarkan beberapa tujuan per organisasi, masing-masing dengan secret, status, dan langganannya sendiri ke subset jenis peristiwa. Ini adalah model yang direkomendasikan untuk semua integrasi baru.

Bandingkan dengan webhook URL tunggal lama, yang dipertahankan untuk kompatibilitas mundur tetapi hanya mendukung satu URL per organisasi.

Endpoint#

Objek endpoint#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Jenis peristiwa yang valid#

events divalidasi terhadap kumpulan persis ini — nilai di luar daftar mengembalikan 400. Lihat Katalog peristiwa untuk bentuk payload setiap jenis.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

Status endpoint#

• active — pengiriman berjalan normal.
• disabled — dijeda secara manual melalui PATCH. Tidak ada permintaan yang dikirim. Kami tidak pernah mengubah status endpoint disabled; mengubahnya kembali menjadi active selalu merupakan keputusan Anda.
• failing — ditetapkan otomatis saat pengiriman ke endpoint menghabiskan seluruh jadwal coba ulangnya (8 percobaan selama 24 jam) tanpa pernah menerima 2xx. Endpoint yang gagal tidak menerima lalu lintas lebih lanjut. Setelah endpoint diperbaiki, PATCH statusnya kembali ke active; pengiriman yang jadwal coba ulangnya belum habis akan dilanjutkan dari tempat terakhirnya.

Daftarkan endpoint#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Mengembalikan array objek Endpoint.

Buat endpoint#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

Kolom permintaan#

Mengembalikan 201 Created dengan objek Endpoint serta kolom secret tingkat atas tambahan yang berisi kunci penandatanganan mentah — sebuah string heksadesimal 48 karakter:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

Perbarui endpoint#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

Mengembalikan 200 OK dengan objek Endpoint yang diperbarui.

Kirim pengiriman uji#

Kirim event webhook.test sintetis ke satu endpoint menggunakan alur pengiriman normal, termasuk serialisasi JSON kanonis, X-ThunderPhone-Signature, pencatatan pengiriman, dan pencatatan percobaan ulang. Uji ini menargetkan endpoint yang dipilih terlepas dari filter events-nya.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Endpoint menerima amplop seperti berikut:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

API mengembalikan 200 OK setelah percobaan pertama, bahkan jika tujuan mengembalikan error. Periksa success, status, response_code, dan error untuk hasil pengiriman:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test bersifat sintetis dan tidak dapat ditambahkan ke langganan events endpoint. Jika percobaan pertama gagal, pengiriman mengikuti jadwal percobaan ulang yang sama seperti pengiriman event normal.

Hapus endpoint#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Mengembalikan 204 No Content. Pengiriman ke URL berhenti segera; percobaan ulang yang sedang berlangsung dibatalkan.

Terkait#