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 yang penting.

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 saat percobaan ulang dan menjaga setiap pengiriman tetap kecil.

Jenis peristiwa yang didukung

Mendaftarkan endpoint

Kunjungi Manage > Webhooks di Claude Console.

Sebuah 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. Sebuah endpoint hanya menerima peristiwa yang dilangganinya.
• Signing secret: Secret 32-byte berawalan whsec_ yang dihasilkan 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-parse peristiwa dalam satu langkah. Helper ini 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 peristiwa

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

Setiap payload peristiwa memiliki struktur yang sama, termasuk jenis peristiwa, pengenal, dan timestamp kapan peristiwa tersebut 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 membuangnya.

Perilaku pengiriman

• Duplikat: Sebuah endpoint dapat menerima peristiwa 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: Sebuah peristiwa hanya dikirimkan ke endpoint yang berlangganan jenisnya pada saat peristiwa itu dipancarkan. Peristiwa yang dipancarkan saat tidak ada endpoint yang berlangganan jenisnya tidak akan pernah dikirimkan, dan berlangganan di kemudian hari tidak akan mengisinya kembali, jadi berlanggananlah ke suatu 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 hasilnya diproduksi lebih dulu, dan peristiwa .deleted dapat tiba sebelum peristiwa .archived untuk sumber daya yang sama. Kendalikan status Anda berdasarkan sumber daya yang Anda ambil, bukan berdasarkan urutan kedatangan peristiwa.

• Percobaan ulang: Untuk setiap endpoint dan peristiwa, Anthropic melakukan hingga tiga percobaan pengiriman (respons yang memicu penonaktifan otomatis, yang 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 tersebut dibuang: tidak diantrekan untuk pengiriman nanti dan tidak ada sinyal bahwa peristiwa itu 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 peristiwa: gunakan created_at pada payload peristiwa untuk mengetahui kapan peristiwa terjadi.

• Penonaktifan otomatis: Sebuah 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 waktunya, sehingga satu peristiwa yang tidak stabil tidak dapat menonaktifkan endpoint.

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