Einen Webhook einrichten

Du brauchst webhooks:write (und webhooks:read, um das Protokoll zu lesen). Dein Endpunkt muss über https auf Port 443 erreichbar sein und darf nicht auf ein internes Netz zeigen (webhook_url_invalid).

#1. Den Endpunkt anlegen

curlPythonTypeScript

curl -X POST "https://api.smartchat.marketing/v1/webhook-endpoints" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/smartchat",
  "description": "Quickstart",
  "enabled_events": [
    "webhook.test"
  ]
}'

import os
import requests

response = requests.post(
    "https://api.smartchat.marketing/v1/webhook-endpoints",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
    json={
        "url": "https://example.com/hooks/smartchat",
        "description": "Quickstart",
        "enabled_events": [
            "webhook.test",
        ],
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.smartchat.marketing/v1/webhook-endpoints", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com/hooks/smartchat",
    "description": "Quickstart",
    "enabled_events": [
      "webhook.test"
    ]
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Response (201):

{
  "object": "webhook_endpoint",
  "id": "whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "url": "https://example.com/hooks/smartchat",
  "description": "Quickstart",
  "enabled_events": [
    "webhook.test"
  ],
  "status": "active",
  "disabled_reason": null,
  "secret_hint": "whsec_...x9Qa",
  "consecutive_failures": 0,
  "last_success_at": "2026-10-25T09:45:00Z",
  "last_failure_at": null,
  "secret_previous_expires_at": null,
  "created_at": "2026-10-25T09:41:07Z",
  "updated_at": "2026-10-25T09:45:00Z",
  "secret": "whsec_3Zk0sQ1mYv9bT7cWl2nR8xJdE4fGhUaPoIyKtVq5LwM"
}

Die Antwort enthält das Geheimnis (whsec_...) ein einziges Mal. Bewahre es sicher auf. Später siehst du nur noch einen Hinweis darauf.

#2. Ein Test-Ereignis senden

curlPythonTypeScript

curl -X POST "https://api.smartchat.marketing/v1/webhook-endpoints/whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234/test" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"

import os
import requests

response = requests.post(
    "https://api.smartchat.marketing/v1/webhook-endpoints/whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234/test",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.smartchat.marketing/v1/webhook-endpoints/whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Response (200):

{
  "object": "webhook_test_result",
  "endpoint_id": "whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "delivery_id": "whd_7a1b2c3d4e5f40718293a4b5c6d7e8f9",
  "delivered": true,
  "http_status": 200,
  "duration_ms": 182,
  "error": null
}

Dein Server bekommt ein Ereignis webhook.test mit einer Signatur.

#3. Die Signatur in deinem Code prüfen

Vertraue nie einer Zustellung, ohne ihre Signatur zu prüfen. Kopiere den Code aus Eine Signatur prüfen.

#4. Die Zustellungen ansehen

curlPythonTypeScript

curl "https://api.smartchat.marketing/v1/webhook-endpoints/whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234/deliveries?status=failed&limit=20" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"

import os
import requests

response = requests.get(
    "https://api.smartchat.marketing/v1/webhook-endpoints/whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234/deliveries",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
    params={
        "status": "failed",
        "limit": "20",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.smartchat.marketing/v1/webhook-endpoints/whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234/deliveries?status=failed&limit=20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Response (200):

{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": "whd_7a1b2c3d4e5f40718293a4b5c6d7e8f9",
      "endpoint_id": "whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
      "event_id": "evt_0f8c1a2e4b7d4c3e9a5b6d7e8f905678",
      "type": "contact.created",
      "attempt": 1,
      "status": "delivered",
      "http_status": 200,
      "error": null,
      "duration_ms": 182,
      "next_attempt_at": null,
      "created_at": "2026-10-25T09:44:59Z",
      "finished_at": "2026-10-25T09:45:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/webhook-endpoints/whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234/deliveries"
}

Schlägt dein Endpunkt immer wieder fehl, wird er pausiert und später abgeschaltet. Siehe Wiederholungen und Zustand.