Endpoint Webhook

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

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

Bandingkan dengan webhook URL tunggal legacy, 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",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Tipe peristiwa valid#

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

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (dicadangkan; belum dipancarkan)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated tidak memiliki konteks agen dan hanya dikirimkan ke endpoint seluruh organisasi.

voice.ready dan voice.failed tidak dapat dipilih secara eksplisit. Untuk menerimanya, buat endpoint seluruh organisasi dengan events: []. Daftar peristiwa kosong menerima setiap peristiwa yang didukung kecuali telephony.turn dan web.turn, yang harus dipilih secara eksplisit.

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 secara otomatis ketika pengiriman ke endpoint menghabiskan seluruh jadwal percobaannya (8 percobaan selama 24 jam) tanpa pernah mendapatkan respons 2xx. Endpoint yang gagal tidak menerima trafik lebih lanjut. Kami mengirim email kepada pemilik dan admin organisasi Anda ketika ini terjadi, dan dasbor menampilkan endpoint yang dijeda dengan tombol Aktifkan kembali. Setelah endpoint diperbaiki, ubah statusnya kembali menjadi active melalui PATCH; pengiriman yang jadwal percobaannya belum habis akan dilanjutkan dari titik terakhirnya.

Daftar endpoint#

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

Mengembalikan array objek Endpoint. Teruskan ?agent_id=42 untuk mengembalikan hanya endpoint yang dicakup agen tersebut.

Endpoint dalam cakupan agen#

Endpoint seluruh organisasi menerima setiap peristiwa yang cocok. Endpoint dengan agent_id hanya menerima peristiwa yang cocok untuk panggilan yang ditangani agen tersebut; peristiwa tanpa konteks agen, seperti alert.triggered, tidak pernah mencapainya. Anda juga dapat membuat dan mengelola endpoint ini dari bagian Webhook di pembuat agen.

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"]

Bidang permintaan#

Mengembalikan 201 Created dengan Objek endpoint yang diperbarui serta bidang secret tingkat teratas 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.

Putar ulang rahasia penandatanganan#

Ganti rahasia penandatanganan endpoint, misalnya ketika rahasia tersebut hilang atau mungkin bocor. Untuk endpoint yang dicakup agen, Anda juga dapat menggunakan dasbor: buka bagian Webhook agen dan pilih Buat ulang rahasia pada endpoint. Endpoint di seluruh organisasi diputar ulang melalui API.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Mengembalikan 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

Kirim pengiriman uji#

Kirim event webhook.test sintetis ke satu endpoint menggunakan pipeline pengiriman normal, termasuk serialisasi JSON kanonis, kedua header tanda tangan, pencatatan pengiriman, dan pencatatan percobaan ulang. Pengujian 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 envelope 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, ThunderPhone mencoba ulang sekali sekitar satu menit kemudian lalu berhenti; pengiriman kemudian menampilkan status: "failed" di bawah Debug pengiriman. Pengiriman uji tidak pernah menandai endpoint sebagai failing.

Untuk mengonfigurasi pemicu berdasarkan bentuk peristiwa nyata, teruskan event_type opsional. Pengiriman tetap sintetis dan berisi "sample": true; sampel terkait panggilan menggunakan call_id: 0 dan agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type menerima nilai apa pun dari Jenis peristiwa yang valid. Mengabaikannya mempertahankan perilaku webhook.test generik.

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 segera berhenti; percobaan ulang yang sedang berlangsung dibatalkan.

Debug pengiriman#

Sebelum menyimpulkan bahwa webhook tidak dikirim, periksa GET /v1/developer/webhook-deliveries. Ini menampilkan percobaan terbaru dari kedua sistem webhook, termasuk ID panggilan, asal URL, status HTTP, jumlah percobaan, kategori kegagalan yang diizinkan, dan waktu percobaan ulang berikutnya. Ini tidak pernah mengembalikan payload peristiwa, transkrip, teks error yang disimpan, badan respons, atau jalur URL.

Anda juga dapat melihat riwayat terbaru yang sama di Agen → pilih agen → Webhooks → Pengiriman terbaru. Baris menampilkan label endpoint dan asal URL yang digunakan oleh percobaan terbaru. Ini adalah status operasional, bukan log audit yang tidak dapat diubah: menghapus endpoint juga menghapus baris pengirimannya.

Untuk 404 n8n, pertama pastikan workflow aktif, menerima POST, dan menggunakan URL webhook produksi, bukan URL pengujian. 401 atau 403 menunjukkan masalah autentikasi atau validasi tanda tangan; timeout menunjukkan latensi atau ketersediaan tujuan; error TLS menunjukkan rantai sertifikat, hostname, atau masa berlaku.

Terkait#