API-Referenz

Webhook-Endpoints

Ein Webhook-Endpoint ist eine URL von dir, die die Ereignisse von Gemlead in dem Moment empfängt, in dem sie eintreten. Du kannst 10 pro Konto haben. Unter Webhooks findest du die Ereignisse, ihre Payloads und wie du eine Signatur prüfst.

Endpoints

GET/v1/webhook_endpoints
POST/v1/webhook_endpoints
GET/v1/webhook_endpoints/:id
PATCH/v1/webhook_endpoints/:id
DELETE/v1/webhook_endpoints/:id
POST/v1/webhook_endpoints/:id/roll_secret
POST/v1/webhook_endpoints/:id/test
GET/v1/webhook_endpoints/:id/deliveries

Das Endpoint-Objekt

Eine URL von dir, an die Gemlead Ereignisse sendet. Unter Webhooks findest du die Ereignisse und wie du sie prüfst.

Attribute

idstring
Eindeutige Kennung des Endpoints.
objectstring
Immer webhook_endpoint.
urlstring
Die HTTPS-URL, an die Ereignisse gesendet werden.
descriptionstring oder null
Deine Notiz zum Endpoint.
eventsArray von strings
Die Ereignistypen, die an ihn gesendet werden.
lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
statusstring
Ob Ereignisse an ihn gesendet werden.
enableddisabled
filtersobject
Welche Ereignisse er bekommt, nach der Persona des Leads. Die Filter gelten für jeden Ereignistyp.
disabled_reasonstring oder null
Warum er deaktiviert ist. manual, wenn du ihn ausgeschaltet hast, failing, wenn Gemlead das nach 3 Tagen mit Fehlern in Folge und mindestens 8 fehlgeschlagenen Versuchen getan hat. null, solange er aktiv ist.
manualfailing
secretstring
Das Signatur-Secret, whsec_ und 32 Zeichen. Nur in den Antworten von Erstellen und Secret erneuern.
created_atstring
Wann der Endpoint erstellt wurde, ISO 8601.
updated_atstring
Wann sich der Endpoint zuletzt geändert hat, ISO 8601.

Das Endpoint-Objekt

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Webhook-Endpoints auflisten

GET/v1/webhook_endpointsScope read

Gibt deine Webhook-Endpoints zurück, ohne ihre Secrets.

Query-Parameter

limitinteger
Wie viele Objekte zurückgegeben werden, von 1 bis 100. Standardmäßig 25.
cursorstring
Der next_cursor der vorherigen Seite, um die nächste Seite abzurufen. Siehe Paginierung.

Rückgabe

Eine Liste von Endpoint-Objekten.

GET/v1/webhook_endpoints

curl https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

{
  "object": "list",
  "data": [
    {
      "id": "wh3LpX9dKe",
      "object": "webhook_endpoint",
      "url": "https://example.com/webhooks/gemlead",
      "description": "CRM sync",
      "events": ["lead.hot", "reply.received"],
      "status": "enabled",
      "filters": {
        "persona_ids": ["lvWBPnytpS"]
      },
      "disabled_reason": null,
      "created_at": "2026-09-14T09:21:05.300Z",
      "updated_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Webhook-Endpoint erstellen

POST/v1/webhook_endpointsScope write

Registriert eine URL für einen oder mehrere Ereignistypen. Speichere das secret aus der Antwort, du siehst es nur dieses eine Mal.

Body-Parameter

urlstringErforderlich
Eine HTTPS-URL, die im öffentlichen Internet erreichbar ist.
eventsArray von stringsErforderlich
Die zu sendenden Ereignistypen.
lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
descriptionstring
Eine Notiz für dich.
filtersobject
Welche Ereignisse gesendet werden, nach der Persona des Leads.

Rückgabe

Das neue Endpoint-Objekt mit seinem secret.

Fehler

400parameter_missing
Ein Pflichtparameter fehlt. param nennt ihn.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.
400parameter_unknown
Der Body enthält ein Feld, das dieser Endpoint nicht akzeptiert.
400url_invalid
Die URL ist kein HTTPS, enthält Zugangsdaten oder zeigt auf eine private Adresse.
400webhook_endpoint_limit_reached
Das Konto hat schon 10 Endpoints.

POST/v1/webhook_endpoints

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot", "reply.received"],
    "description": "CRM sync",
    "filters": {
      "persona_ids": ["lvWBPnytpS"]
    }
  }'

Antwort200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z",
  "secret": "whsec_4QeX7nP2kR9tLm3Vb8YzC1dF6hJ0sWuA"
}

Webhook-Endpoint abrufen

GET/v1/webhook_endpoints/:idScope read

Gibt einen Webhook-Endpoint zurück, ohne sein Secret.

Pfadparameter

idstringErforderlich
Die ID des Webhook-Endpoints.

Rückgabe

Ein Endpoint-Objekt.

Fehler

404resource_missing
Kein Webhook-Endpoint mit dieser ID im Konto des Schlüssels.

GET/v1/webhook_endpoints/:id

curl https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Webhook-Endpoint ändern

PATCH/v1/webhook_endpoints/:idScope write

Ändert einen Endpoint. Setze status auf enabled, um einen Endpoint wieder einzuschalten, den Gemlead deaktiviert hat. Einschalten oder eine neue url setzt seinen Fehlerzähler zurück.

Pfadparameter

idstringErforderlich
Die ID des Webhook-Endpoints.

Body-Parameter

urlstring
Eine neue HTTPS-URL.
eventsArray von strings
Die zu sendenden Ereignistypen.
lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
descriptionstring
Eine Notiz für dich.
statusstring
Den Endpoint ein- oder ausschalten.
enableddisabled
filtersobject
Welche Ereignisse gesendet werden, nach der Persona des Leads.

Rückgabe

Das aktualisierte Endpoint-Objekt.

Fehler

404resource_missing
Kein Webhook-Endpoint mit dieser ID im Konto des Schlüssels.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.
400parameter_unknown
Der Body enthält ein Feld, das dieser Endpoint nicht akzeptiert.
400url_invalid
Die URL ist kein HTTPS, enthält Zugangsdaten oder zeigt auf eine private Adresse.

PATCH/v1/webhook_endpoints/:id

curl -X PATCH \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "enabled"
  }'

Antwort200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Webhook-Endpoint löschen

DELETE/v1/webhook_endpoints/:idScope write

Löscht einen Endpoint. Zustellungen, die noch auf einen neuen Versuch warten, werden verworfen.

Pfadparameter

idstringErforderlich
Die ID des Webhook-Endpoints.

Rückgabe

Ein Objekt mit der id des Endpoints und dem Wert true in deleted.

Fehler

404resource_missing
Kein Webhook-Endpoint mit dieser ID im Konto des Schlüssels.

DELETE/v1/webhook_endpoints/:id

curl -X DELETE \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "deleted": true
}

Signatur-Secret erneuern

POST/v1/webhook_endpoints/:id/roll_secretScope write

Ersetzt das Secret des Endpoints sofort, das alte funktioniert nicht mehr. Zustellungen, die in der Zwischenzeit fehlschlagen, werden erneut versucht und mit dem neuen Secret signiert.

Pfadparameter

idstringErforderlich
Die ID des Webhook-Endpoints.

Rückgabe

Das Endpoint-Objekt mit seinem neuen secret.

Fehler

404resource_missing
Kein Webhook-Endpoint mit dieser ID im Konto des Schlüssels.

POST/v1/webhook_endpoints/:id/roll_secret

curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/roll_secret \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z",
  "secret": "whsec_4QeX7nP2kR9tLm3Vb8YzC1dF6hJ0sWuA"
}

Testereignis senden

POST/v1/webhook_endpoints/:id/testScope write

Sendet ein Beispielereignis vom ersten Ereignistyp des Endpoints, mit dem Wert true in data.test und IDs, die mit test_ beginnen. Ein Versuch, keine Wiederholung.

Pfadparameter

idstringErforderlich
Die ID des Webhook-Endpoints.

Rückgabe

Ein Zustellungsobjekt mit dem status und dem status_code, mit denen dein Endpoint geantwortet hat.

Fehler

404resource_missing
Kein Webhook-Endpoint mit dieser ID im Konto des Schlüssels.

POST/v1/webhook_endpoints/:id/test

curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

{
  "id": "dL5qW1zXa8",
  "object": "webhook_delivery",
  "endpoint_id": "wh3LpX9dKe",
  "event_id": "evt_8kQ2vXr4LmT9wPz1Hc6YbN3d",
  "event_type": "lead.hot",
  "status": "succeeded",
  "attempts": 1,
  "status_code": 200,
  "error": null,
  "test": true,
  "next_attempt_at": null,
  "last_attempt_at": "2026-11-06T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Das Zustellungsobjekt

Ein Ereignis, das an einen Endpoint gesendet wurde, mit seinen Versuchen und der letzten Antwort deines Servers.

Attribute

idstring
Eindeutige Kennung der Zustellung.
objectstring
Immer webhook_delivery.
endpoint_idstring
Der Endpoint, an den sie gesendet wurde.
event_idstring
Das gesendete Ereignis, die id, die dein Server erhalten hat.
event_typestring
Der Typ des Ereignisses.
lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
statusstring
pending, solange noch Versuche übrig sind, dann succeeded oder failed.
pendingsucceededfailed
attemptsinteger
Bisherige Versuche, höchstens 8.
status_codeinteger oder null
Der HTTP-Status deiner letzten Antwort. null, wenn es keine gab, nach einem Timeout oder einem Verbindungsfehler.
errorstring oder null
Was beim letzten Versuch schiefgelaufen ist, etwa der Status und der Anfang deiner Antwort, oder ein Timeout.
testboolean
true für ein Testereignis.
next_attempt_atstring oder null
Wann der nächste Versuch fällig ist, solange pending.
last_attempt_atstring oder null
Wann der letzte Versuch stattfand.
created_atstring
Wann die Zustellung erstellt wurde, ISO 8601.

Das Zustellungsobjekt

{
  "id": "dR7mK2pVn4",
  "object": "webhook_delivery",
  "endpoint_id": "wh3LpX9dKe",
  "event_id": "evt_3Hn7QpW2xZk9LmR4tV8bYc1D",
  "event_type": "reply.received",
  "status": "pending",
  "attempts": 2,
  "status_code": 503,
  "error": "HTTP 503: Service Unavailable",
  "test": false,
  "next_attempt_at": "2026-11-06T08:18:10.000Z",
  "last_attempt_at": "2026-11-06T08:13:10.000Z",
  "created_at": "2026-11-06T08:12:10.000Z"
}

Zustellungen auflisten

GET/v1/webhook_endpoints/:id/deliveriesScope read

Gibt die letzten Zustellungen des Endpoints zurück, die neuesten zuerst, Testereignisse eingeschlossen. Zustellungen werden 30 Tage aufbewahrt.

Pfadparameter

idstringErforderlich
Die ID des Webhook-Endpoints.

Query-Parameter

limitinteger
Wie viele Zustellungen zurückgegeben werden, von 1 bis 100. Standardmäßig 25.

Rückgabe

Eine Liste von Zustellungsobjekten. Diese Liste hat keinen next_cursor, erhöhe limit, um mehr zu sehen.

Fehler

404resource_missing
Kein Webhook-Endpoint mit dieser ID im Konto des Schlüssels.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.

GET/v1/webhook_endpoints/:id/deliveries

curl -G \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/deliveries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d limit=10

Antwort200

{
  "object": "list",
  "data": [
    {
      "id": "dR7mK2pVn4",
      "object": "webhook_delivery",
      "endpoint_id": "wh3LpX9dKe",
      "event_id": "evt_3Hn7QpW2xZk9LmR4tV8bYc1D",
      "event_type": "reply.received",
      "status": "pending",
      "attempts": 2,
      "status_code": 503,
      "error": "HTTP 503: Service Unavailable",
      "test": false,
      "next_attempt_at": "2026-11-06T08:18:10.000Z",
      "last_attempt_at": "2026-11-06T08:13:10.000Z",
      "created_at": "2026-11-06T08:12:10.000Z"
    },
    {
      "id": "dL5qW1zXa8",
      "object": "webhook_delivery",
      "endpoint_id": "wh3LpX9dKe",
      "event_id": "evt_8kQ2vXr4LmT9wPz1Hc6YbN3d",
      "event_type": "lead.hot",
      "status": "succeeded",
      "attempts": 1,
      "status_code": 200,
      "error": null,
      "test": true,
      "next_attempt_at": null,
      "last_attempt_at": "2026-11-06T07:45:12.904Z",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}