Berlangganan webhook

Sesi adalah interaksi yang berjalan lama. Meskipun sebagian besar interaksi real-time terjadi melalui event stream 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. Ini menghindari pengiriman data usang saat percobaan ulang dan menjaga setiap pengiriman tetap kecil.



Tipe event yang didukung



Daftarkan endpoint

Kunjungi Manage > Webhooks di Console.

Sebuah endpoint webhook terdiri dari:

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



Verifikasi 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 lima 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() akan 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



Tangani event

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

Setiap payload event memiliki struktur yang sama, termasuk tipe event, pengidentifikasi, 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 mengabaikannya.



Perilaku pengiriman

• Duplikat: Sebuah 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: Sebuah event hanya dikirimkan ke endpoint yang berlangganan tipenya pada saat event tersebut dikeluarkan. Event yang dikeluarkan saat tidak ada endpoint yang berlangganan tipenya tidak akan pernah dikirimkan, dan berlangganan kemudian tidak akan mengisi ulang event tersebut, jadi berlanggananlah ke suatu tipe event sebelum Anda membutuhkannya.

• Urutan tidak dijamin. Event tidak dikirimkan sesuai urutan terjadinya: session.status_idled dapat tiba sebelum session.outcome_evaluation_ended meskipun hasilnya diproduksi lebih dulu, dan event .deleted dapat tiba sebelum event .archived untuk sumber daya yang sama. Kendalikan state Anda dari sumber daya yang Anda ambil, bukan dari 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 ber-jitter antara 5 dan 120 detik. Setiap percobaan mengirimkan event.id yang sama. Setelah percobaan terakhir gagal, event tersebut 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: 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 menonaktifkan endpoint segera, 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 ter-resolve ke alamat IP non-publik saat Anthropic terhubung. Ini menonaktifkan endpoint segera, 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 mengatur ulang jendela tersebut, sehingga satu event yang tidak stabil tidak dapat menonaktifkan endpoint.

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