Endpoint Webhook

Sistem webhook berbasis endpoint memungkinkan Anda mendaftarkan beberapa tujuan per organisasi, masing-masing dengan secret, status, dan langganannya sendiri terhadap sebagian 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

Metode	Path	Peran yang diperlukan	Deskripsi
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Mencantumkan endpoint
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Membuat endpoint
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Memperbarui label / URL / peristiwa / status
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Menghapus endpoint
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Mengirim pengiriman uji yang ditandatangani

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

Bidang	Tipe	Deskripsi
`id`	UUID	ID endpoint
`label`	string	Nama tampilan, 1–120 karakter
`url`	string	URL HTTPS; `http://localhost` diizinkan untuk pengembangan
`events`	array of string	Jenis peristiwa yang dilanggani (lihat nilai valid). Array kosong melanggani semua peristiwa
`status`	string	`active`, `disabled` (dijeda secara manual), atau `failing` (diatur otomatis saat suatu pengiriman menghabiskan jadwal percobaan ulang 24 jamnya tanpa satu pun 2xx)
`secret_hint`	string	4 karakter pertama dan 4 karakter terakhir dari secret penandatanganan dengan elipsis (`a1b2…9f0e`) — cukup untuk mencocokkan secret yang Anda simpan secara lokal tanpa mengekspos nilai lengkapnya
`created_at`, `updated_at`	timestamp

secret lengkap endpoint dikembalikan sekali saat pembuatan dan tidak pernah lagi. Simpan dengan aman — jika Anda kehilangannya, hapus endpoint lalu buat kembali.

Jenis peristiwa yang valid

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

telephony.incoming, telephony.complete, telephony.tool
web.incoming, web.complete, web.tool
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 — diatur secara otomatis saat pengiriman ke endpoint menghabiskan seluruh jadwal percobaan ulangnya (8 percobaan selama 24 jam) tanpa pernah mendapatkan 2xx. Endpoint yang gagal tidak menerima traffic lebih lanjut. Setelah endpoint diperbaiki, lakukan PATCH pada statusnya kembali menjadi active; pengiriman yang jadwal percobaan ulangnya belum habis akan dilanjutkan dari titik terakhirnya.

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

Field permintaan

Field	Tipe	Wajib	Deskripsi
`label`	string	ya	1–120 karakter
`url`	string	ya	URL HTTPS (`http` hanya diizinkan untuk `localhost` / `127.0.0.1`)
`events`	array	tidak	Kosong/tidak disertakan akan berlangganan ke semua event. Harus menggunakan nilai yang tercantum dalam Tipe event yang valid; duplikat akan dihapus

Mengembalikan 201 Created dengan objek Endpoint serta field 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"
}

secret dikembalikan hanya saat pembuatan. Respons GET berikutnya hanya menyertakan secret_hint. Salin nilai lengkap ke pengelola rahasia Anda sebelum menutup respons.

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

Field	Tipe	Deskripsi
`label`	string
`url`	string
`events`	array
`status`	string	`active` atau `disabled`. Tetapkan `active` untuk mengaktifkan kembali endpoint yang ditandai server sebagai `failing`

Mengembalikan 200 OK dengan objek Endpoint yang diperbarui.

Kirim pengiriman uji

Kirim event webhook.test sintetis ke satu endpoint menggunakan pipeline pengiriman normal, termasuk serialisasi JSON kanonis, X-ThunderPhone-Signature, pencatatan pengiriman, dan pelacakan percobaan ulang. Pengujian menargetkan endpoint yang dipilih tanpa memedulikan 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, 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 langsung berhenti; percobaan ulang yang sedang berlangsung dibatalkan.

Terkait

Katalog peristiwa

Daftar lengkap nilai events yang dapat Anda langgani.

Ringkasan webhook

Verifikasi tanda tangan dan semantik pengiriman.

Webhooks

Function Tools

Endpoint

Objek endpoint

Jenis peristiwa yang valid

Status endpoint

Mencantumkan endpoint

Buat endpoint

Field permintaan

Perbarui endpoint

Kirim pengiriman uji

Hapus endpoint

Terkait

Katalog peristiwa

Ringkasan webhook

​Endpoint

​Objek endpoint

​Jenis peristiwa yang valid

​Status endpoint

​Mencantumkan endpoint

​Buat endpoint

​Field permintaan

​Perbarui endpoint

​Kirim pengiriman uji

​Hapus endpoint

​Terkait

Katalog peristiwa

Ringkasan webhook

Endpoint

Objek endpoint

Jenis peristiwa yang valid

Status endpoint

Mencantumkan endpoint

Buat endpoint

Field permintaan

Perbarui endpoint

Kirim pengiriman uji

Hapus endpoint

Terkait