> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 terhadap sebagian jenis peristiwa. Ini adalah
model yang direkomendasikan untuk semua integrasi baru.

Bandingkan dengan [webhook URL tunggal lama](/api-reference/organizations#legacy-single-url-webhook),
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

```json theme={null}
{
  "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](#valid-event-types)). 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       |                                                                                                                                                                                                      |

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

### Jenis peristiwa yang valid

`events` divalidasi terhadap kumpulan tepat ini — nilai di luar daftar
mengembalikan `400`. Lihat [Katalog peristiwa](/id/webhooks/events) 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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

Mengembalikan array [objek Endpoint](#endpoint-object).

***

## Buat endpoint

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```python Python theme={null}
  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"]
  ```
</CodeGroup>

### 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](#valid-event-types); duplikat akan dihapus |

Mengembalikan `201 Created` dengan [objek Endpoint](#endpoint-object) serta
field `secret` tingkat teratas tambahan yang berisi kunci penandatanganan mentah — sebuah
string heksadesimal 48 karakter:

```json theme={null}
{
  "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"
}
```

<Warning>
  `secret` dikembalikan **hanya saat pembuatan**. Respons `GET` berikutnya
  hanya menyertakan `secret_hint`. Salin nilai lengkap ke pengelola rahasia Anda
  sebelum menutup respons.
</Warning>

***

## Perbarui endpoint

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

| 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](#endpoint-object) 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

Endpoint menerima envelope seperti berikut:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

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

***

## Terkait

<CardGroup cols={2}>
  <Card title="Katalog peristiwa" icon="list" href="/id/webhooks/events">
    Daftar lengkap nilai `events` yang dapat Anda langgani.
  </Card>

  <Card title="Ringkasan webhook" icon="bolt" href="/id/webhooks/overview">
    Verifikasi tanda tangan dan semantik pengiriman.
  </Card>
</CardGroup>