Webhooks

Réponse directe

Contrats de webhook de messagerie et de financement vérifiés, gestion des doublons et comportement de rapprochement actuel.

Contenu source

# Webhooks

TextTree accepte actuellement les rappels du fournisseur à partir de deux limites :

- événements du fournisseur de messagerie
- Peer pour le financement d'événements

Toutes les routes de webhook sont des points de terminaison JSON servis par Phoenix.

## Points de terminaison

- rappels d'événements signés du fournisseur de messagerie
- rappels entrants signés du fournisseur de messagerie
-`POST /webhooks/peer/events`

Les points de terminaison des webhooks clients sont configurés à partir de la page Webhooks authentifiés. Les itinéraires de
Les webhooks du fournisseur précédent sont les rappels du fournisseur entrants que TextTree utilise pour mettre à jour
le statut des messages, des annulations (opt-out) et du financement.

## Types d'événements clients

Abonnez votre point de terminaison aux événements dont votre application a besoin :

-`message.sent`
-`message.delivered`
-`message.failed`
-`message.received`
-`conversation.created`
-`conversation.updated`
-`opt_out.created`

## Forme des événements clients

Les charges utiles des webhooks clients utilisent un wrapper stable afin que les récepteurs puissent passer par `type` et
inspectez l’objet de domaine à `data`.

```json
{
"identifiant": "evt_123",
"type": "message.délivré",
"created_at": "2026-04-28T14:00:00Z",
"données": {
"message": {
"identifiant": "msg_123",
"status": "livré",
"numéro_téléphone": "+15551234567",
"segments": 1,
"cost_cents": 1
    }
  }
}
```

Renvoie toute réponse `2xx` pour marquer la livraison comme réussie. Les réponses non `2xx` sont conservées pour
débogage et réessayer/rejouer depuis la console.

## Vérification des signatures

La vérification du webhook est obligatoire dans la phase alpha actuelle.

- Les demandes du fournisseur de messagerie doivent inclure l'en-tête de signature configuré
- Les demandes du fournisseur pour SMS doivent inclure l'horodatage et les en-têtes de signature configurés.
- Les demandes des pairs doivent inclure `x-peer-timestamp` et `x-peer-signature`
- Les valeurs de signature utilisent le format `sha256=<hex>`

La signature est calculée comme un HMAC-SHA256 sur l'horodatage et la représentation canonique
de la charge utile TextTree, et non les octets bruts de la requête. TextTree rejette les paires horodatage/signature
manquants, obsolètes, futurs ou dépareillés ; La fenêtre de fraîcheur par défaut est de cinq minutes.

## Réponse d'acceptation

Un webhook vérifié qui réussit la validation de forme renvoie `202 Accepted` :

```json
{
"identifiant": "8fca25fd-d7b7-4f58-8bdd-d4ab4ca3ae97",
"status": "reçu",
"provider": "messaging_provider",
"event_type": "message.delivered",
"external_id": "provider_evt_123",
"duplicata": faux
}
```

Si les mêmes `event_type` et `external_id` sont renvoyés par le même fournisseur, TextTree renvoie le
enregistrement existant avec `"duplicate": true` et ne met pas en file d'attente les travaux en double en aval.

## Réponses aux échecs

- `401` avec `{"error":"invalid_signature"}` lorsque la vérification échoue
- `422` avec `{"error":"invalid_webhook_payload"}` lorsque la requête est signée mais qu'il manque le
champs obligatoires pour l'identité de l'événement

## Lecture depuis la console

Tout échec de livraison de webhook client doit être reproductible une fois le point de terminaison corrigé. Le flux
Replay préserve la charge utile d'origine et enregistre une nouvelle tentative de livraison avec le code de réponse, la latence et
corps de réponse.

```txt
Webhooks → sélectionner le point de terminaison → ouvrir la livraison ayant échoué → rejouer le webhook
```

## Gestion des événements de messagerie

Les charges utiles du fournisseur de messagerie sont normalisées à l'aide de clés telles que `type`, `id`, `message_id` et `metadata`.

### Événements de message rapprochés

-`message.sent`
-`message.delivered`
-`message.failed`

Ceux-ci mettent à jour l’état en aval du message et peuvent renseigner les identifiants du fournisseur dans le message stocké.

### Événements de désinscription rapprochés

-`recipient.opted_out`
-`contact.opted_out`
-`message.opted_out`
-`message.unsubscribed`

Dans la V1, ceux-ci créent ou mettent à jour des suppressions au niveau de l'espace de travail avec les métadonnées du fournisseur. Le
Les suppressions d'espace de travail bloquent les soumissions uniques à partir de l'interface utilisateur, les soumissions API du développeur, les soumissions MCP et
diffusions de campagne pour ce numéro de téléphone.

## Gestion des événements homologues

Les charges utiles des pairs sont normalisées à partir de clés telles que `event`, `event_id`, `session_id`, `amount_cents`
et `metadata`.

### Événements de financement rapprochés

-`funding.completed`
-`funding.failed`
-`funding.expired`

Les événements de financement terminés mettent à jour le statut de la session de financement et créent des crédits idempotents dans le grand livre.
Les événements de financement ayant échoué ou expiré mettent à jour l'état stocké de la session de financement pour examen par l'opérateur.

## Exemples

### Événement de messagerie livré

```json
{
"type": "message.délivré",
"id": "provider_evt_123",
"message_id": "msg_123"
}
```

### Événement de désinscription de la messagerie

```json
{
"type": "recipient.opted_out",
"id": "provider_evt_456",
"numéro_téléphone": "+15551234567",
"message_id": "msg_123"
}
```

### Événement de financement par les pairs

```json
{
"event": "funding.completed",
"event_id": "peer_evt_123",
"session_id": "session_123",
"montant_cents": 500
}
```

## Notes opérationnelles

- Les événements fournisseur sont conservés avant la réconciliation asynchrone.
- Les événements ayant échoué restent visibles dans `/app` avec les raisons de l'échec et les commandes de lecture.
- La lecture est destinée à la récupération de l'opérateur une fois les données sous-jacentes ou les problèmes de fournisseur corrigés.
- Les événements inconnus mais valablement signés peuvent être stockés et ignorés jusqu'à ce que la couche de domaine les prenne en charge.