Berlangganan webhook

Sesi adalah interaksi yang berjalan lama. Meskipun sebagian besar interaksi real-time terjadi melalui aliran peristiwa SSE, webhook memberi tahu Anda tentang perubahan status utama.

Peristiwa webhook mengembalikan type dan id peristiwa, bukan objek lengkapnya. Saat Anda menerima peristiwa webhook, Anda perlu mengambil objek tersebut secara langsung dengan panggilan GET. Hal ini menghindari pengiriman data usang pada percobaan ulang dan menjaga setiap pengiriman tetap kecil.



Jenis peristiwa yang didukung



Mendaftarkan endpoint

Kunjungi Manage > Webhooks di Claude Console.

Endpoint webhook terdiri dari:

• URL: Harus HTTPS pada port 443 dengan hostname yang dapat di-resolve secara publik.
• Jenis peristiwa: Daftar nilai data.type yang diterima endpoint ini. Endpoint hanya menerima peristiwa yang dilanggannya.
• Signing secret: Secret 32-byte dengan prefiks whsec_ yang dihasilkan saat pembuatan. Secret ini hanya ditampilkan sekali, jadi simpan dengan aman untuk memverifikasi pengiriman webhook.



Memverifikasi signature

Setiap pengiriman membawa header webhook-id, webhook-timestamp, dan webhook-signature. Gunakan helper unwrap() dari SDK untuk memverifikasi signature dan mem-parse peristiwa dalam satu langkah. Helper ini akan melempar error jika signature tidak valid atau payload berusia lebih dari 5 menit.

Atur ANTHROPIC_WEBHOOK_SIGNING_KEY ke secret dengan prefiks whsec_ yang ditampilkan saat pembuatan endpoint.

from flask import Flask, request
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
app = Flask(__name__)


@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        # unwrap() memunculkan error jika tanda tangan tidak valid atau payload sudah kedaluwarsa
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            headers=dict(request.headers),
        )
    except Exception:
        return "invalid signature", 400

    if event.data.type == "session.status_idled":
        print("session idled:", event.data.id)
    # tangani tipe event lainnya

    return "", 200



Menangani peristiwa

Parse body, lakukan switch pada data.type, dan ambil sumber daya berdasarkan ID. Kembalikan 2xx apa pun untuk mengonfirmasi. Respons lainnya akan dihitung terhadap endpoint: 3xx langsung menonaktifkannya (redirect tidak pernah diikuti), sementara kegagalan lainnya akan dicoba ulang; lihat Perilaku pengiriman untuk aturan percobaan ulang dan penonaktifan otomatis.

Setiap payload peristiwa memiliki struktur yang sama, termasuk jenis peristiwa, identifier, dan timestamp kapan peristiwa terjadi.

{
  "type": "event",
  "id": "whe_9d5c1f7e...",
  "created_at": "2026-03-18T14:05:22Z",
  "data": {
    "type": "session.status_idled",
    "id": "sesn_01XYZ...",
    "organization_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}

if event.data.type == "session.status_idled":
    session = client.beta.sessions.retrieve(event.data.id)
    notify_user(session)
return "", 204

event.id tingkat atas bersifat unik per peristiwa, bukan per pengiriman. Jika Anda menerima event.id yang sama dua kali, itu adalah percobaan ulang dan Anda dapat mengabaikannya.



Perilaku pengiriman

• Duplikat: Endpoint dapat menerima peristiwa yang sama lebih dari satu kali, dan setiap percobaan mengirimkan event.id tingkat atas yang sama (nilai yang sama dengan header webhook-id). Lakukan deduplikasi berdasarkan nilai tersebut.

• Cakupan langganan: Peristiwa hanya dikirimkan ke endpoint yang berlangganan jenisnya pada saat peristiwa dikirimkan. Peristiwa yang dikirimkan saat tidak ada endpoint yang berlangganan jenisnya tidak akan pernah dikirimkan, dan berlangganan setelahnya tidak akan mengisi ulang peristiwa tersebut, jadi berlanggananlah ke jenis peristiwa sebelum Anda membutuhkannya.

• Urutan tidak dijamin. Peristiwa tidak dikirimkan sesuai urutan terjadinya: session.status_idled mungkin tiba sebelum session.outcome_evaluation_ended meskipun hasil diproduksi lebih dulu, dan peristiwa .deleted dapat tiba sebelum peristiwa .archived untuk sumber daya yang sama. Tentukan status Anda berdasarkan sumber daya yang Anda ambil, bukan dari urutan kedatangan peristiwa.

• Percobaan ulang: Untuk setiap endpoint dan peristiwa, Anthropic melakukan hingga tiga percobaan pengiriman (respons yang memicu penonaktifan otomatis, dijelaskan nanti di bagian ini, tidak pernah dicoba ulang) dengan exponential backoff ber-jitter antara 5 dan 120 detik. Setiap percobaan mengirimkan event.id yang sama. Setelah percobaan terakhir gagal, peristiwa dibuang: tidak diantrekan untuk pengiriman nanti dan tidak ada sinyal bahwa peristiwa tersebut hilang. Webhook bukanlah log yang tahan lama, jadi jika Anda perlu mengamati setiap transisi, lakukan rekonsiliasi dengan membuat daftar atau mengambil sumber daya melalui API.

• Timestamp: Header webhook-timestamp dicap saat percobaan pengiriman ditandatangani dan dibuat ulang pada setiap percobaan ulang, sehingga percobaan ulang tidak ditolak oleh pemeriksaan kesegaran SDK. Ini adalah waktu untuk percobaan pengiriman, bukan untuk peristiwa: gunakan created_at dari payload peristiwa untuk mengetahui kapan peristiwa terjadi.

• Penonaktifan otomatis: Endpoint secara otomatis diatur ke disabled dengan disabled_reason yang dapat dibaca mesin dalam tiga kasus:

  • Endpoint mengembalikan respons 3xx. Redirect tidak pernah diikuti; ini langsung menonaktifkan endpoint, pada percobaan pertama, dengan alasan auto-disabled: endpoint URL returned a redirect (3xx). Jika endpoint Anda berpindah, perbarui URL di Console dan aktifkan kembali endpoint tersebut.
  • URL endpoint di-resolve ke alamat IP non-publik saat Anthropic terhubung. Ini langsung menonaktifkan endpoint, dengan alasan auto-disabled: endpoint URL resolved to an invalid address.
  • Pengiriman ke endpoint gagal terus-menerus selama periode yang berkelanjutan, dengan alasan auto-disabled after sustained delivery failures. Pemicunya adalah berapa lama endpoint telah gagal tanpa gangguan, bukan jumlah pengiriman. Satu 2xx akan mengatur ulang jendela tersebut, sehingga satu peristiwa yang tidak stabil tidak dapat menonaktifkan endpoint.

  Ketiganya dapat dibalik: aktifkan kembali endpoint di Console setelah Anda menyelesaikan masalahnya. Peristiwa yang dikirimkan saat endpoint dinonaktifkan tidak diputar ulang.