Webhooks: Ereignisse an externe Systeme
Webhooks senden automatisch Nachrichten an eine externe URL bei bestimmten Ereignissen in Tesoro, z. B. neuer Lead, Deal auf Won-Status, Immobilie auf Sold. Wird für Integrationen mit Zapier, Make oder eigenen Systemen verwendet.
Wann verwenden Sie es?
Abschnitt betitelt „Wann verwenden Sie es?“- Neuen Lead über Zapier an einen Slack-Kanal senden
- Deal-Won-Ereignis an Ihr Buchhaltungssystem senden
- Externes Analyse-Tool Echtzeitdaten empfangen lassen
Was ist ein Webhook?
Abschnitt betitelt „Was ist ein Webhook?“Bei jedem ausgewählten Ereignis sendet Tesoro eine HTTP-POST-Anfrage an Ihre URL mit einer JSON-Payload. Ihr System empfängt, verarbeitet und antwortet (200 OK).
Einen Webhook erstellen
Abschnitt betitelt „Einen Webhook erstellen“- Settings → Webhooks → Add webhook.
- Füllen Sie aus:
- Name: einprägsamer Name
- URL: Endpunkt, der die Payload empfängt (HTTPS empfohlen)
- Events: wählen Sie aus, welche Ereignisse auslösen
- Secret (optional), zur Anfragevalidierung
- Save → Webhook aktiv.
Verfügbare Ereignisse
Abschnitt betitelt „Verfügbare Ereignisse“| Kategorie | Ereignisse |
|---|---|
| Lead | created, updated, status_changed, converted, deleted |
| Kontakt | created, updated, deleted, portal_user_created |
| Deal | created, status_changed, won, lost, deleted |
| Immobilie | created, status_changed, sold, rented, deleted |
| Meeting | created, status_changed, completed |
| Aktivität | task_created, task_completed, note_created |
Wählen Sie mindestens 1 aus, mehrere sind möglich.
Payload-Format
Abschnitt betitelt „Payload-Format“JSON-Body enthält:
event: Typ (z. B.lead.created)timestamp: wanndata: vollständiger Datensatz mit allen Feldernprevious_data(bei Änderungen), vorheriger Statuscompany_id: für Multi-Tenant-Integrationen
Authentifizierung + Sicherheit
Abschnitt betitelt „Authentifizierung + Sicherheit“Secret-Validierung (empfohlen): Tesoro signiert jeden Webhook mit HMAC. Ihr Endpunkt berechnet den gleichen HMAC und validiert.
Ohne Secret: Jede POST kann von jeder Quelle kommen. Nicht empfohlen für Produktionssysteme.
Wiederholungsverhalten
Abschnitt betitelt „Wiederholungsverhalten“Webhook fehlgeschlagen (keine 200-Antwort innerhalb von X Sekunden oder Netzwerk-Timeout)? Tesoro versucht es erneut:
- 1 Minute später
- 5 Minuten später
- 30 Minuten später
- 2 Stunden später
- Danach als Failed markiert, keine weiteren Versuche
Fehlgeschlagene Webhooks sind im Dashboard sichtbar. Manueller erneuter Versuch möglich.
Webhook-Protokolle
Abschnitt betitelt „Webhook-Protokolle“Pro Webhook sehen Sie die letzten Versuche:
- Zeitstempel
- Ereignistyp
- Antwortstatus
- Anzahl der Wiederholungen
- Body (ein/aus)
Hilft beim Debuggen.
Häufige Fehler
Abschnitt betitelt „Häufige Fehler“Keine Ereignisse empfangen
Abschnitt betitelt „Keine Ereignisse empfangen“Prüfen Sie:
- Ist die URL vom Internet aus erreichbar?
- Ist das HTTPS-Zertifikat gültig?
- Sendet der Endpunkt eine 200-Antwort innerhalb von 5 Sekunden?
- Sind die Ereignisse tatsächlich in der Webhook-Konfiguration ausgewählt?
Doppelte Ereignisse
Abschnitt betitelt „Doppelte Ereignisse“Webhook-Wiederholungsverhalten: Bei Timing-Problemen erhalten Sie manchmal eine Wiederholung einer bereits erfolgreichen Zustellung. Machen Sie Ihren Endpunkt idempotent: dieselbe Ereignis-ID zweimal empfangen → einmal verarbeiten.