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 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 dilanggannya, ditambah peristiwa uji (lihat Perilaku pengiriman).
• 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 X-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 lima 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 resource berdasarkan ID. Kembalikan 2xx apa pun untuk mengonfirmasi. Apa pun selain itu (termasuk 3xx) dihitung sebagai kegagalan dan memicu percobaan ulang.

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

{
  "type": "event",
  "id": "event_01ABC...",
  "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

• Urutan tidak dijamin. session.status_idled mungkin tiba sebelum session.outcome_evaluation_ended meskipun hasil dihasilkan terlebih dahulu. Gunakan timestamp created_at untuk mengurutkan jika urutan penting.
• Percobaan ulang: Anthropic mencoba ulang setidaknya sekali. Percobaan ulang mengirimkan event.id yang sama.
• Redirect tidak diikuti. 3xx diperlakukan sebagai kegagalan. Jika endpoint Anda berpindah, perbarui URL di Console.
• Penonaktifan otomatis: Sebuah endpoint secara otomatis diatur ke disabled dengan disabled_reason yang dapat dibaca mesin setelah sekitar 20 pengiriman gagal berturut-turut, atau segera jika hostname di-resolve ke IP privat atau endpoint mengembalikan redirect. Aktifkan kembali secara manual di Console setelah menyelesaikan masalah.