> ## Documentation Index
> Fetch the complete documentation index at: https://docs.setteo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound webhooks

> Envoyez des prospects à Setteo depuis Make, n8n, un tunnel de vente ou tout autre outil, pour les créer, les taguer ou les inscrire dans un scénario.

Un webhook entrant permet à un outil externe d'envoyer un prospect à Setteo par une simple requête `POST`. Selon l'URL appelée, Setteo crée ou met à jour le prospect, lui ajoute un tag ou l'inscrit dans un scénario.

Pour recevoir les événements Setteo sur votre serveur, utilisez les [webhooks sortants](https://docs.setteo.io/api-reference/automations.md).

## URLs

Les webhooks entrants sont servis par `https://webhooks.setteo.io`.

| URL | Effet |
| - | - |
| `/leads/{token}` | Crée ou met à jour le prospect. |
| `/tags/{token}` | Crée ou met à jour le prospect, puis lui ajoute le tag. |
| `/scenarios/{token}` | Crée ou met à jour le prospect, puis l'inscrit dans le scénario. |

Chaque URL accepte deux méthodes :

* `POST` envoie un prospect.
* `GET` vérifie que l'URL existe, sans rien modifier. La réponse est `200` avec le statut `ready`.

```text theme={null}
https://webhooks.setteo.io/tags/<token>
```

## Authentification

Il n'y a pas d'en-tête `Authorization` : le `{token}` de l'URL est le seul secret. Traitez l'URL complète comme un mot de passe et ne la partagez pas.

Chaque tag et chaque scénario a son propre token :

* **Tag** : copiez le champ **Webhook url** depuis la page du tag.
* **Scénario** : ouvrez le nœud **Début du scénario**. L'URL est affichée sous **Par webhook** une fois le scénario créé.

Un token inconnu renvoie toujours la même réponse `404`, quelle que soit l'URL appelée.

## Corps de la requête

Envoyez un corps JSON avec l'en-tête `Content-Type: application/json`.

| Champ | Type | Description |
| - | - | - |
| `email` | string | Adresse e-mail, 255 caractères maximum. |
| `phone` | string | Numéro de téléphone. |
| `lead_id` | integer | Identifiant d'un prospect Setteo existant. `id` est accepté à la place. |
| `first_name` | string | Prénom, 255 caractères maximum. |
| `last_name` | string | Nom, 255 caractères maximum. |
| `variables` | object | Variables du prospect. `customData` est accepté en complément. |
| `tags` | array ou string | Libellés de tags, en liste ou séparés par des virgules. |
| `ghl_id` | string | Identifiant GoHighLevel du contact. |

Il faut au moins un `email`, un `phone` ou un `lead_id`. Si vous n'avez qu'un champ de nom, vous pouvez l'envoyer dans `name`, `full_name` ou `fullName`.

```bash theme={null}
curl --request POST \
  --url https://webhooks.setteo.io/tags/<token> \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Jean",
    "last_name": "Dupont",
    "email": "jean.dupont@example.com",
    "phone": "+33612345678",
    "variables": { "source_campagne": "webinaire" },
    "tags": ["Webinaire", "Inscrit"]
  }'
```

### Règles de traitement

* **Doublons** : Setteo cherche d'abord le prospect par `lead_id`, puis par `phone`, puis par `email`. S'il existe, il est mis à jour au lieu d'être dupliqué. Un `lead_id` inconnu est refusé avec une erreur `404`.
* **E-mail seul** : le `phone` n'est pas obligatoire. Sans prospect existant, un nouveau prospect est créé avec l'e-mail.
* **Numéros** : un numéro sans indicatif est lu avec la région de votre espace de travail. Un numéro invalide est refusé avec une erreur `422`.
* **Variables** : elles sont ajoutées à celles du prospect. Leurs clés sont converties en `snake_case` : les caractères qui ne sont ni des lettres ni des chiffres deviennent `_`.
* **Tags** : un libellé qui n'existe pas encore est créé.

### Formats d'outils reconnus

Setteo lit aussi directement les payloads envoyés par ces outils, sans mapping de votre part : ActiveCampaign, GoHighLevel, systeme.io, ClickFunnels, Circle, iClosed et Kajabi.

## Réponses

Toutes les réponses sont en JSON.

```json theme={null}
{
  "success": true,
  "status": "tag_attached",
  "message": "Tag added."
}
```

| Code | `status` | Cas |
| - | - | - |
| `200` | `ready` | Réponse à un `GET`. |
| `200` | `lead_saved` | Prospect enregistré (`/leads`). |
| `200` | `tag_attached` | Prospect enregistré et tag ajouté (`/tags`). |
| `200` | `enrolled` | Prospect inscrit dans le scénario (`/scenarios`). |
| `200` | `already_enrolled` | Le prospect est déjà dans le scénario. |
| `404` | `not_found` | Token inconnu. |
| `404` | `lead_not_found` | Le `lead_id` ne correspond à aucun prospect. |
| `422` | `target_inactive` | Le scénario n'est pas actif. |
| `422` | | Validation refusée : champ manquant, e-mail ou numéro invalide. Le champ `errors` détaille chaque champ. |
| `500` | `enrollment_failed` | Le prospect n'a pas pu être inscrit dans le scénario. |

## Limites de taux

Les webhooks entrants sont limités, par défaut, à **480 requêtes par minute et par adresse IP**. Au-delà, Setteo répond `429 Too Many Requests`.

## Anciennes URLs

Les anciennes URLs de webhooks entrants continuent de fonctionner, mais ne sont plus la référence. Pour tout nouveau branchement, utilisez les URLs de cette page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.