Webhooks

Direkte Antwort

Verifizierte Messaging- und Finanzierungs-Webhook-Verträge, Duplikatbehandlung und aktuelles Abgleichsverhalten.

Seiteninhalt

# Webhooks

TextTree akzeptiert derzeit Anbieterrückrufe ab zwei Limits:

- Ereignisse des Messaging-Anbieters
- Peer für die Finanzierung von Veranstaltungen

Alle Webhook-Routen sind JSON-Endpunkte, die von Phoenix bereitgestellt werden.

## Endpunkte

- signierte Ereignisrückrufe vom Messaging-Anbieter
- signierte eingehende Rückrufe vom Messaging-Anbieter
- `POST /webhooks/peer/events`

Client-Webhooks-Endpunkte werden über die authentifizierte Webhooks-Seite konfiguriert. Die Routen von
Frühere Anbieter-Webhooks sind die eingehenden Anbieter-Rückrufe, die TextTree zum Aktualisieren verwendet
den Status von Nachrichten, Stornierungen (Opt-out) und Finanzierung.

## Client-Ereignistypen

Abonnieren Sie Ihren Endpunkt für die Ereignisse, die Ihre Anwendung benötigt:

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

## Form von Kundenveranstaltungen

Client-Webhook-Nutzlasten verwenden einen stabilen Wrapper, sodass Empfänger über `type` und weiterleiten können
Überprüfen Sie das Domänenobjekt unter `data`.

```json
{
  „id“: „evt_123“,
  „type“: „message.delivered“,
  „created_at“: „2026-04-28T14:00:00Z“,
  "Daten": {
    „Nachricht“: {
      „id“: „msg_123“,
      „status“: „geliefert“,
      „phone_number“: „+15551234567“,
      „Segmente“: 1,
      „cost_cents“: 1
    }
  }
}
```

Gibt eine beliebige `2xx`-Antwort zurück, um die Zustellung als erfolgreich zu markieren. Antworten, die nicht `2xx` sind, bleiben erhalten
Debuggen und erneutes Versuchen/Wiederholen über die Konsole.

## Signaturüberprüfung

Die Webhook-Verifizierung ist in der aktuellen Alpha-Phase obligatorisch.

- Anfragen des Messaging-Anbieters müssen den konfigurierten Signatur-Header enthalten
- SMS-Anbieteranfragen müssen die konfigurierten Zeitstempel- und Signatur-Header enthalten
– Peer-Anfragen müssen `x-peer-timestamp` und `x-peer-signature` enthalten
– Signaturwerte verwenden das Format `sha256=<hex>`

Die Signatur wird als HMAC-SHA256 über den Zeitstempel und die kanonisierte Darstellung berechnet
der TextTree-Nutzlast, nicht auf den Rohbytes der Anfrage. TextTree lehnt Zeitstempel/Signatur-Paare ab
fehlend, veraltet, in der Zukunft oder nicht übereinstimmend; Das standardmäßige Frischefenster beträgt fünf Minuten.

## Akzeptanzantwort

Ein verifizierter Webhook, der die Formvalidierung besteht, gibt `202 Accepted` zurück:

```json
{
  „id“: „8fca25fd-d7b7-4f58-8bdd-d4ab4ca3ae97“,
  „status“: „empfangen“,
  „provider“: „messaging_provider“,
  „event_type“: „message.delivered“,
  „external_id“: „provider_evt_123“,
  „Duplikat“: falsch
}
```

Wenn dasselbe `event_type` und `external_id` erneut vom selben Anbieter gesendet werden, gibt TextTree das zurück
vorhandenen Datensatz mit `"duplicate": true` und stellt keine doppelten Downstream-Arbeiten in die Warteschlange.

## Fehlerantworten

- `401` mit `{"error":"invalid_signature"}`, wenn die Überprüfung fehlschlägt
- `422` mit `{"error":"invalid_webhook_payload"}`, wenn die Anfrage signiert ist, aber das fehlt
  Erforderliche Felder für die Ereignisidentität

## Wiedergabe von der Konsole

Jede fehlgeschlagene Client-Webhook-Zustellung sollte reproduzierbar sein, nachdem Sie den Endpunkt repariert haben. Der Fluss
Replay behält die ursprüngliche Nutzlast bei und zeichnet einen neuen Zustellungsversuch mit Antwortcode, Latenz und auf
Antwortkörper.

```txt
Webhooks → Endpunkt auswählen → fehlgeschlagene Zustellung öffnen → Webhook erneut abspielen
```

## Messaging-Ereignisbehandlung

Die Nutzdaten des Messaging-Anbieters werden aus Schlüsseln wie `type`, `id`, `message_id` und `metadata` normalisiert.

### Nachrichtenereignisse abgeglichen

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

Diese aktualisieren den Downstream-Status der Nachricht und können Anbieterkennungen in die gespeicherte Nachricht einfügen.

### Abgeglichene Opt-out-Ereignisse

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

In V1 erstellen oder aktualisieren diese Löschungen auf Arbeitsbereichsebene mit Anbietermetadaten. Die
Durch das Löschen von Arbeitsbereichen werden einmalige Übermittlungen über die Benutzeroberfläche, Entwickler-API-Übermittlungen, MCP-Übermittlungen usw. blockiert
Kampagnenlieferungen für diese Telefonnummer.

## Peer-Ereignisbehandlung

Peer-Payloads werden aus Schlüsseln wie `event`, `event_id`, `session_id`, `amount_cents` normalisiert
und `metadata`.

### Abgeglichene Förderveranstaltungen

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

Abgeschlossene Finanzierungsereignisse aktualisieren den Status der Finanzierungssitzung und erstellen idempotente Gutschriften im Hauptbuch.
Fehlgeschlagene und abgelaufene Finanzierungsereignisse aktualisieren den gespeicherten Status der Finanzierungssitzung zur Überprüfung durch den Betreiber.

## Beispiele

### Messaging-Ereignis zugestellt

```json
{
  „type“: „message.delivered“,
  „id“: „provider_evt_123“,
  „message_id“: „msg_123“
}
```

### Messaging-Opt-out-Ereignis

```json
{
  „type“: „recipient.opted_out“,
  „id“: „provider_evt_456“,
  „phone_number“: „+15551234567“,
  „message_id“: „msg_123“
}
```

### Peer-Funding-Veranstaltung

```json
{
  „event“: „funding.completed“,
  „event_id“: „peer_evt_123“,
  „session_id“: „session_123“,
  „amount_cents“: 500
}
```

## Betriebshinweise

- Lieferantenereignisse werden vor dem asynchronen Abgleich beibehalten.
– Fehlgeschlagene Ereignisse bleiben in `/app` mit Fehlergründen und Wiedergabesteuerungen sichtbar.
- Die Wiedergabe dient der Wiederherstellung durch den Bediener, nachdem zugrunde liegende Daten- oder Anbieterprobleme behoben wurden.
– Unbekannte, aber gültig signierte Ereignisse können gespeichert und ignoriert werden, bis die Domänenschicht sie unterstützt.