Gemlead
Docs
Se connecter
Obtenir ta clé API

Référence API

Endpoints webhook

Un endpoint webhook est une de tes URL qui reçoit les événements de Gemlead au moment où ils se produisent. Tu peux en avoir 10 par compte. Lis Webhooks pour les événements, leurs payloads et la vérification des signatures.

Endpoints

L'objet endpoint webhook

Une de tes URL à laquelle Gemlead envoie des événements. Voir Webhooks pour les événements et leur vérification.

Attributs

  • idstring
    Identifiant unique de l'endpoint.
  • objectstring
    Toujours webhook_endpoint.
  • urlstring
    L'URL HTTPS à laquelle les événements sont envoyés.
  • descriptionstring ou null
    Ta note sur l'endpoint.
  • eventstableau de strings
    Les types d'événements qui lui sont envoyés.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    Si des événements lui sont envoyés.
    enableddisabled
  • filtersobject
    Les événements qu'il reçoit, selon le persona du lead. Ces filtres s'appliquent à tous les types d'événements.
  • disabled_reasonstring ou null
    Pourquoi il est désactivé. manual quand tu l'as désactivé, failing quand Gemlead l'a fait après 3 jours d'échecs de suite et au moins 8 tentatives ratées. null tant qu'il est activé.
    manualfailing
  • secretstring
    Le secret de signature, whsec_ suivi de 32 caractères. Seulement dans les réponses à la création et au renouvellement du secret.
  • created_atstring
    Date de création de l'endpoint, en ISO 8601.
  • updated_atstring
    Date de la dernière modification de l'endpoint, en ISO 8601.
L'objet 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"
}

Lister les endpoints webhook

GET/v1/webhook_endpointsScope read

Renvoie tes endpoints webhook, sans leurs secrets.

Paramètres de requête

  • limitinteger
    Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
  • cursorstring
    Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets endpoint webhook.

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

Créer un endpoint webhook

POST/v1/webhook_endpointsScope write

Enregistre une URL pour un ou plusieurs types d'événements. Garde le secret de la réponse, c'est la seule fois que tu le vois.

Paramètres du corps

  • urlstringObligatoire
    Une URL HTTPS joignable depuis Internet.
  • eventstableau de stringsObligatoire
    Les types d'événements à envoyer.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    Une note pour toi.
  • filtersobject
    Les événements à envoyer, selon le persona du lead.

Renvoie

Le nouvel objet endpoint webhook avec son secret.

Erreurs

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"]
    }
  }'
Réponse200
{
  "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"
}

Récupérer un endpoint webhook

GET/v1/webhook_endpoints/:idScope read

Renvoie un endpoint webhook, sans son secret.

Paramètres de chemin

  • idstringObligatoire
    L'ID de l'endpoint webhook.

Renvoie

Un objet endpoint webhook.

Erreurs

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

Modifier un endpoint webhook

PATCH/v1/webhook_endpoints/:idScope write

Modifie un endpoint. Mets status à enabled pour réactiver un endpoint que Gemlead a désactivé. Le réactiver ou lui donner une nouvelle url remet son compteur d'échecs à zéro.

Paramètres de chemin

  • idstringObligatoire
    L'ID de l'endpoint webhook.

Paramètres du corps

  • urlstring
    Une nouvelle URL HTTPS.
  • eventstableau de strings
    Les types d'événements à envoyer.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    Une note pour toi.
  • statusstring
    Activer ou désactiver l'endpoint.
    enableddisabled
  • filtersobject
    Les événements à envoyer, selon le persona du lead.

Renvoie

L'objet endpoint webhook à jour.

Erreurs

  • 404resource_missing
    Aucun endpoint webhook avec cet ID sur le compte de la clé.
  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
  • 400parameter_unknown
    Le corps contient un champ que cet endpoint n'accepte pas.
  • 400url_invalid
    L'URL n'est pas en HTTPS, contient des identifiants ou pointe vers une adresse privée.
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"
  }'
Réponse200
{
  "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"
}

Supprimer un endpoint webhook

DELETE/v1/webhook_endpoints/:idScope write

Supprime un endpoint. Les envois qui attendent encore une nouvelle tentative sont abandonnés.

Paramètres de chemin

  • idstringObligatoire
    L'ID de l'endpoint webhook.

Renvoie

Un objet avec l'id de l'endpoint et deleted à true.

Erreurs

DELETE/v1/webhook_endpoints/:id
curl -X DELETE \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "deleted": true
}

Renouveler le secret de signature

POST/v1/webhook_endpoints/:id/roll_secretScope write

Remplace aussitôt le secret de l'endpoint, et l'ancien ne fonctionne plus. Les envois qui échouent entre-temps sont renvoyés, signés avec le nouveau secret.

Paramètres de chemin

  • idstringObligatoire
    L'ID de l'endpoint webhook.

Renvoie

L'objet endpoint webhook avec son nouveau secret.

Erreurs

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"
Réponse200
{
  "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"
}

Envoyer un événement test

POST/v1/webhook_endpoints/:id/testScope write

Envoie un événement d'exemple du premier type d'événement de l'endpoint, avec data.test à true et des ID qui commencent par test_. Un seul essai, sans nouvelle tentative.

Paramètres de chemin

  • idstringObligatoire
    L'ID de l'endpoint webhook.

Renvoie

Un objet envoi de webhook avec le status et le status_code renvoyés par ton endpoint.

Erreurs

POST/v1/webhook_endpoints/:id/test
curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "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'objet envoi de webhook

Un événement envoyé à un endpoint, avec ses tentatives et la dernière réponse de ton serveur.

Attributs

  • idstring
    Identifiant unique de l'envoi.
  • objectstring
    Toujours webhook_delivery.
  • endpoint_idstring
    L'endpoint destinataire.
  • event_idstring
    L'événement envoyé, l'id que ton serveur a reçu.
  • event_typestring
    Le type de l'événement.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    pending tant qu'il reste des tentatives, puis succeeded ou failed.
    pendingsucceededfailed
  • attemptsinteger
    Tentatives faites jusqu'ici, 8 au plus.
  • status_codeinteger ou null
    Le statut HTTP de ta dernière réponse. null s'il n'y en a pas eu, après un timeout ou une erreur de connexion.
  • errorstring ou null
    Ce qui n'a pas marché à la dernière tentative, comme le statut et le début de ta réponse, ou un timeout.
  • testboolean
    true pour un événement test.
  • next_attempt_atstring ou null
    Date de la prochaine tentative, tant que le statut est pending.
  • last_attempt_atstring ou null
    Date de la dernière tentative.
  • created_atstring
    Date de création de l'envoi, en ISO 8601.
L'objet envoi de 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"
}

Lister les envois

GET/v1/webhook_endpoints/:id/deliveriesScope read

Renvoie les derniers envois de l'endpoint, du plus récent au plus ancien, événements test compris. Les envois sont conservés 30 jours.

Paramètres de chemin

  • idstringObligatoire
    L'ID de l'endpoint webhook.

Paramètres de requête

  • limitinteger
    Nombre d'envois à renvoyer, de 1 à 100. 25 par défaut.

Renvoie

Une liste d'objets envoi de webhook. Cette liste n'a pas de next_cursor, augmente limit pour en voir plus.

Erreurs

  • 404resource_missing
    Aucun endpoint webhook avec cet ID sur le compte de la clé.
  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
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
Réponse200
{
  "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
}
Reçois les nouveautés de Gemlead
directement dans ta boîte mail.
S'abonner
En t'abonnant, tu acceptes notre Politique de confidentialité et l'envoi de nos nouveautés.
Gemlead
Produit
Commencer
Se connecter
Pour qui
Agents IA
Fonctionnalités
Tarifs
Affiliation
FAQ
Fonctionnalités
Tes acheteurs, 24/7Leads chauds d'abord60 %+ de réponsesDes DM sur mesureTous les DM, une inboxTon closer IAScale sans limiteAPI, MCP, webhooksDemande à Gemlead
Ressources
AccueilAPIBlog
Juridique
Conditions
Confidentialité
© 2026 Gemlead, Inc. Tous droits réservés.
Français