Berlangganan webhook

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

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

Jenis event yang didukung

Mendaftarkan endpoint

Di Claude Console, buka halaman Webhooks (platform.claude.com/settings/workspaces/default/webhooks). Setiap endpoint dimiliki oleh satu workspace. Pilih workspace yang Anda inginkan di pemilih workspace pada sidebar.

Endpoint webhook terdiri dari:

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

Memverifikasi tanda tangan

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

Atur ANTHROPIC_WEBHOOK_SIGNING_KEY ke secret berawalan 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 jenis event lainnya

    return "", 200

Menangani event

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

Setiap payload event memiliki struktur yang sama, termasuk jenis event, pengenal, dan timestamp kapan event 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 event, bukan per pengiriman. Jika Anda menerima event.id yang sama dua kali, itu adalah percobaan ulang dan Anda dapat membuangnya.

Perilaku pengiriman

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

• Cakupan langganan: Event hanya dikirimkan ke endpoint yang berlangganan jenisnya pada saat event dipancarkan. Event yang dipancarkan saat tidak ada endpoint yang berlangganan jenisnya tidak akan pernah dikirimkan, dan berlangganan kemudian tidak akan mengisinya kembali, jadi berlanggananlah ke suatu jenis event sebelum Anda membutuhkannya.

• Urutan tidak dijamin. Event tidak dikirimkan sesuai urutan terjadinya: session.status_idled mungkin tiba sebelum session.outcome_evaluation_ended meskipun hasilnya dihasilkan lebih dulu, dan event .deleted dapat tiba sebelum event .archived untuk sumber daya yang sama. Tentukan state Anda berdasarkan sumber daya yang Anda ambil, bukan berdasarkan urutan kedatangan event.

• Percobaan ulang: Untuk setiap endpoint dan event, Anthropic melakukan hingga tiga percobaan pengiriman (respons yang memicu penonaktifan otomatis, yang dijelaskan nanti di bagian ini, tidak pernah dicoba ulang) dengan "exponential backoff" (penundaan eksponensial) ber-jitter antara 5 dan 120 detik. Setiap percobaan mengirimkan event.id yang sama. Setelah percobaan terakhir gagal, event dibuang: event tidak diantrekan untuk pengiriman nanti dan tidak ada sinyal bahwa event tersebut hilang. Webhook bukanlah log yang tahan lama, jadi jika Anda perlu mengamati setiap transisi, lakukan rekonsiliasi dengan mendaftar 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 jam untuk percobaan pengiriman, bukan untuk event: gunakan created_at dari payload event untuk mengetahui kapan event 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 jeda, bukan jumlah pengiriman. Satu 2xx saja akan mengatur ulang jendela waktu tersebut, sehingga satu event yang tidak stabil tidak dapat menonaktifkan endpoint.

  Ketiganya dapat dipulihkan: aktifkan kembali endpoint di Console setelah Anda menyelesaikan masalahnya. Event yang dipancarkan saat endpoint dinonaktifkan tidak akan diputar ulang.