Referentie inkomende contacten-webhook

Contacten komen via één HTTP-verzoek in de automatiseringswachtrij. Deze pagina is de referentie voor dat verzoek, voor wie het aansluit: jij, een ontwikkelaar of een Zapier-stap. Gebruik je Zapier, dan loopt Zapier koppelen aan Trustaroo hetzelfde verzoek door in de interface van Zapier.

Voor E-mailautomatisering heb je Trustaroo Premium nodig

Dit hoort bij Trustaroo Premium. Upgrade in de app onder Instellingen, paneel Subscription, om het aan te zetten.

Het verzoek

POST {API base}/webhooks/automations/{businessProfileId}/contacts

Kopieer de complete URL uit Algemene Instellingen op de pagina Automatisering in plaats van hem zelf samen te stellen. Hij bevat al het kenmerk van je bedrijfsprofiel en eindigt op /contacts. Het pad onder de API-host is /api/webhooks/automations/{businessProfileId}/contacts.

Headers

Header	Verplicht	Waarde
X-Webhook-Secret	Ja	Het Webhook Secret uit Algemene Instellingen.
Content-Type	Ja	application/json

Body

Eén JSON-object.

Veld	Type	Verplicht	Toelichting
email	string	Ja	Moet een geldig e-mailadres zijn. Hier gaan de reviewverzoeken naartoe.
name	string	Nee	Gebruikt voor {{customer_name}} in je e-mails. Laat je hem weg, dan blijft de naam in de aanhef leeg.
locationShortId	string	Nee	De short ID van de locatie waar dit contact bij hoort. Laat je hem weg, dan wordt de terugvallocatie gebruikt.

Voorbeeld van een body:

{
  "email": "customer@example.com",
  "name": "Sarah de Vries",
  "locationShortId": "a1b2c3"
}

Voorbeeldaanroep

curl -X POST \
  "https://api.example.com/api/webhooks/automations/00000000-0000-0000-0000-000000000000/contacts" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-webhook-secret" \
  -d '{"email":"customer@example.com","name":"Sarah de Vries"}'

Vervang de URL en het secret door de waarden uit Algemene Instellingen.

De short ID van de locatie

De short ID is het laatste deel van de reviewlink van een locatie, https://my.trustaroo.app/response/{shortId}. Kopieer hem uit die reviewlink. Zie Je reviewlink delen.

Meesturen is belangrijk als je meerdere locaties hebt, want de reviewlink van het contact, en daarmee de beoordeling die je ophaalt, hangt aan die ene locatie. Een short ID die niet bij je bedrijfsprofiel hoort wordt genegeerd, en dan wordt de terugvallocatie gebruikt.

Een contact heeft op de een of andere manier een locatie nodig

Heeft het verzoek geen bruikbare locationShortId en staat er in Algemene Instellingen geen Fallback Location, dan kan het contact niet worden aangemaakt en mislukt het verzoek. Stel dus een terugvallocatie in voordat je iets koppelt.

Een geslaagd verzoek

Bij succes komt er een 200 OK terug met het kenmerk van het nieuwe contact:

{
  "id": "3f1b0f9e-0c2a-4b7d-9a52-6f7f2b8c1d34",
  "message": "Contact added to automation queue"
}

Op dat moment is het contact:

• zichtbaar in de Contactenwachtrij met de status In Afwachting
• gekoppeld aan de locatie die is bepaald
• in bezit van een eigen reviewlink in de vorm https://my.trustaroo.app/response/{locationShortId}?contact={contactId}
• in afwachting van stap 1, die verstuurd wordt zodra de vertraging is verstreken

Het verzoek zelf mailt niets. Een achtergrondtaak controleert de wachtrij elke 15 minuten en verstuurt wat openstaat, dus een stap met een vertraging van 0 dagen komt binnen ongeveer een kwartier aan.

Een geweigerd verzoek

Status	Betekenis	Oplossing
400 "Automation not enabled"	Automatisering staat uit, of dit bedrijfsprofiel heeft nog geen configuratie voor automatisering.	Schakel Automatisering inschakelen in en kies Instellingen Opslaan.
401 "Invalid webhook secret"	De header X-Webhook-Secret ontbreekt of komt niet overeen.	Kopieer het secret opnieuw met de knop Kopiëren en let op losse spaties.
400 "Invalid email address"	De waarde van email is geen geldig adres.	Controleer de veldkoppeling in het verzendende systeem. Een lege waarde meesturen is de gebruikelijke oorzaak.
500 "Internal server error"	Het contact kon niet worden aangemaakt. Meestal omdat er geen locatie bepaald kon worden.	Stel een Fallback Location in, of stuur een locationShortId mee die bij je bedrijfsprofiel hoort.

Een geweigerd verzoek voegt niets aan de wachtrij toe, dus je kunt de oorzaak veilig oplossen en het opnieuw versturen.

Dubbele contacten

Trustaroo vergelijkt op e-mailadres binnen je configuratie voor automatisering. Staat dat adres al in de wachtrij, dan slaagt het verzoek en komt het bestaande contact terug in plaats van dat er een tweede wordt aangemaakt.

Dat beschermt je tegen een Zap die twee keer afgaat, maar het heeft een gevolg dat je moet weten: een terugkerende klant die al Voltooid of Uitgeschreven is, start geen nieuwe reeks. Wil je die persoon na een later bezoek opnieuw vragen, verwijder hem dan eerst uit de Contactenwachtrij en verstuur het verzoek daarna opnieuw.

Praktische aandachtspunten

Trigger op echte transacties. Eén verzoek per afgeronde verkoop, boeking of klus. De webhook kent geen batches en nergens in Trustaroo zit een lijstupload.

Houd het secret privé. De URL en het secret samen zijn genoeg om contacten aan je wachtrij toe te voegen, dus bewaar ze in de credentialopslag van je koppeling, niet in code die in de browser draait of in een gedeeld document.

Herhaal netjes. Herhaalt je koppeling een verzoek na een netwerkfout, dan zorgt de controle op dubbele adressen ervoor dat er geen tweede contact bijkomt.

Test met je eigen adres. Voeg jezelf toe, kijk of het contact als In Afwachting verschijnt en geef daarna een beoordeling via de link in de e-mail die je ontvangt. Daarmee controleer je beide richtingen in één keer.

Gerelateerde handleidingen

• Zapier koppelen aan TrustarooHetzelfde verzoek, gebouwd in Zapier.
• Automatisering inschakelen en instellenWaar de URL en het secret vandaan komen.
• De contactenwachtrij lezenControleer of een contact aankwam en wat de status is.
• Variabelen in e-mailtemplatesHoe de reviewlink in je e-mails wordt gebruikt.