Gemlead
Docs
Accedi
Ottieni la tua chiave API

Riferimento API

Endpoint webhook

Un endpoint webhook è un tuo URL che riceve gli eventi di Gemlead nel momento in cui accadono. Puoi averne 10 per account. Leggi Webhook per gli eventi, i loro payload e come verificare una firma.

Endpoint

L'oggetto endpoint webhook

Un tuo URL a cui Gemlead invia gli eventi. Vedi Webhook per gli eventi e come verificarli.

Attributi

  • idstring
    Identificatore univoco dell'endpoint.
  • objectstring
    Sempre webhook_endpoint.
  • urlstring
    L'URL HTTPS a cui vengono inviati gli eventi.
  • descriptionstring o null
    La tua nota sull'endpoint.
  • eventsarray di strings
    I tipi di evento che riceve.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    Se gli vengono inviati gli eventi.
    enableddisabled
  • filtersobject
    Quali eventi riceve, in base alla buyer persona del lead. Si applicano a ogni tipo di evento.
  • disabled_reasonstring o null
    Perché è disattivato. manual quando l'hai disattivato tu, failing quando l'ha fatto Gemlead dopo 3 giorni di errori di fila e almeno 8 tentativi falliti. null quando è attivo.
    manualfailing
  • secretstring
    Il segreto di firma, whsec_ e 32 caratteri. Solo nelle risposte di creazione e di rinnovo del segreto.
  • created_atstring
    Quando è stato creato l'endpoint, ISO 8601.
  • updated_atstring
    Quando l'endpoint è cambiato l'ultima volta, ISO 8601.
L'oggetto endpoint webhook
{
  "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"
}

Elenca gli endpoint webhook

GET/v1/webhook_endpointsScope read

Restituisce i tuoi endpoint webhook, senza i loro segreti.

Parametri di query

  • limitinteger
    Quanti oggetti restituire, da 1 a 100. Di default 25.
  • cursorstring
    Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti endpoint webhook.

GET/v1/webhook_endpoints
curl https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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
}

Crea un endpoint webhook

POST/v1/webhook_endpointsScope write

Registra un URL per uno o più tipi di evento. Salva il secret della risposta, perché è l'unica volta che lo vedrai.

Parametri del body

  • urlstringObbligatorio
    Un URL HTTPS raggiungibile da internet.
  • eventsarray di stringsObbligatorio
    I tipi di evento da inviare.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    Una nota per te.
  • filtersobject
    Quali eventi inviare, in base alla buyer persona del lead.

Restituisce

Il nuovo oggetto endpoint webhook con il suo secret.

Errori

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"]
    }
  }'
Risposta200
{
  "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"
}

Recupera un endpoint webhook

GET/v1/webhook_endpoints/:idScope read

Restituisce un endpoint webhook, senza il suo segreto.

Parametri di percorso

  • idstringObbligatorio
    L'ID dell'endpoint webhook.

Restituisce

Un oggetto endpoint webhook.

Errori

  • 404resource_missing
    Nessun endpoint webhook con questo ID sull'account della chiave.
GET/v1/webhook_endpoints/:id
curl https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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"
}

Aggiorna un endpoint webhook

PATCH/v1/webhook_endpoints/:idScope write

Modifica un endpoint. Imposta status su enabled per riattivare un endpoint che Gemlead ha disattivato. Riattivarlo o dargli un nuovo url fa ripartire il conteggio degli errori.

Parametri di percorso

  • idstringObbligatorio
    L'ID dell'endpoint webhook.

Parametri del body

  • urlstring
    Un nuovo URL HTTPS.
  • eventsarray di strings
    I tipi di evento da inviare.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    Una nota per te.
  • statusstring
    Attiva o disattiva l'endpoint.
    enableddisabled
  • filtersobject
    Quali eventi inviare, in base alla buyer persona del lead.

Restituisce

L'oggetto endpoint webhook aggiornato.

Errori

  • 404resource_missing
    Nessun endpoint webhook con questo ID sull'account della chiave.
  • 400parameter_invalid
    Un parametro ha un valore che l'API non accetta. param lo indica.
  • 400parameter_unknown
    Il body ha un campo che questo endpoint non accetta.
  • 400url_invalid
    L'URL non è HTTPS, contiene credenziali o punta a un indirizzo privato.
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"
  }'
Risposta200
{
  "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"
}

Elimina un endpoint webhook

DELETE/v1/webhook_endpoints/:idScope write

Elimina un endpoint. Le consegne ancora in attesa di un nuovo tentativo vengono scartate.

Parametri di percorso

  • idstringObbligatorio
    L'ID dell'endpoint webhook.

Restituisce

Un oggetto con l'id dell'endpoint e deleted impostato su true.

Errori

  • 404resource_missing
    Nessun endpoint webhook con questo ID sull'account della chiave.
DELETE/v1/webhook_endpoints/:id
curl -X DELETE \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "deleted": true
}

Rinnova il segreto di firma

POST/v1/webhook_endpoints/:id/roll_secretScope write

Sostituisce subito il segreto dell'endpoint, e quello vecchio smette di funzionare. Le consegne che falliscono nel frattempo vengono ritentate, firmate con il nuovo segreto.

Parametri di percorso

  • idstringObbligatorio
    L'ID dell'endpoint webhook.

Restituisce

L'oggetto endpoint webhook con il suo nuovo secret.

Errori

  • 404resource_missing
    Nessun endpoint webhook con questo ID sull'account della chiave.
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"
Risposta200
{
  "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"
}

Invia un evento di test

POST/v1/webhook_endpoints/:id/testScope write

Invia un evento di esempio del primo tipo di evento dell'endpoint, con data.test impostato su true e ID che iniziano con test_. Un solo tentativo, senza ripetizioni.

Parametri di percorso

  • idstringObbligatorio
    L'ID dell'endpoint webhook.

Restituisce

Un oggetto consegna webhook con lo status e lo status_code con cui ha risposto il tuo endpoint.

Errori

  • 404resource_missing
    Nessun endpoint webhook con questo ID sull'account della chiave.
POST/v1/webhook_endpoints/:id/test
curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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"
}

L'oggetto consegna webhook

Un evento inviato a un endpoint, con i suoi tentativi e l'ultima risposta del tuo server.

Attributi

  • idstring
    Identificatore univoco della consegna.
  • objectstring
    Sempre webhook_delivery.
  • endpoint_idstring
    L'endpoint a cui è stato inviato.
  • event_idstring
    L'evento inviato, l'id ricevuto dal tuo server.
  • event_typestring
    Il tipo dell'evento.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    pending finché restano tentativi, poi succeeded o failed.
    pendingsucceededfailed
  • attemptsinteger
    Tentativi fatti finora, al massimo 8.
  • status_codeinteger o null
    Lo stato HTTP della tua ultima risposta. null quando non c'è stata, dopo un timeout o un errore di connessione.
  • errorstring o null
    Cosa è andato storto all'ultimo tentativo, come lo stato e l'inizio della tua risposta, oppure un timeout.
  • testboolean
    true per un evento di test.
  • next_attempt_atstring o null
    Quando è previsto il prossimo tentativo, finché è pending.
  • last_attempt_atstring o null
    Quando è stato fatto l'ultimo tentativo.
  • created_atstring
    Quando è stata creata la consegna, ISO 8601.
L'oggetto consegna webhook
{
  "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"
}

Elenca le consegne

GET/v1/webhook_endpoints/:id/deliveriesScope read

Restituisce le ultime consegne dell'endpoint, dalla più recente, eventi di test compresi. Le consegne vengono conservate 30 giorni.

Parametri di percorso

  • idstringObbligatorio
    L'ID dell'endpoint webhook.

Parametri di query

  • limitinteger
    Quante consegne restituire, da 1 a 100. 25 di default.

Restituisce

Un elenco di oggetti consegna webhook. Questo elenco non ha next_cursor, aumenta limit per vederne di più.

Errori

  • 404resource_missing
    Nessun endpoint webhook con questo ID sull'account della chiave.
  • 400parameter_invalid
    Un parametro ha un valore che l'API non accetta. param lo indica.
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
Risposta200
{
  "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
}
Ricevi gli aggiornamenti di Gemlead
direttamente nella tua casella email.
Iscriviti
Iscrivendoti accetti la nostra Informativa sulla privacy e acconsenti a ricevere aggiornamenti dalla nostra azienda.
Gemlead
Prodotto
Inizia
Accedi
Per chi
Agenti IA
Funzionalità
Prezzi
Affiliazione
FAQ
Funzionalità
Acquirenti, 24/7Prima i lead caldiOltre il 60% rispondeDM su misuraTutti i DM in un'inboxIl tuo closer IAScala senza limitiAPI, MCP, webhookChiedi a Gemlead
Risorse
HomeAPIBlog
Note legali
Termini
Privacy
© 2026 Gemlead, Inc. Tutti i diritti riservati.
Italiano