Inbound contacts webhook reference
Contacts enter the automation queue through one HTTP request. This page is the reference for that request, for whoever is wiring it up: you, a developer, or a Zapier step. If you are using Zapier, Connect Zapier to Trustaroo walks through the same request in the Zapier interface.
This is part of Trustaroo Premium. Upgrade from Account and billing in the app to switch it on.
The request
POST {API base}/webhooks/automations/{businessProfileId}/contacts
Copy the finished URL from General Settings on the Automation page rather than assembling it yourself. It already contains your business profile identifier and ends in /contacts. The path under the API host is /api/webhooks/automations/{businessProfileId}/contacts.
Headers
| Header | Required | Value |
|---|---|---|
X-Webhook-Secret | Yes | The Webhook Secret from General Settings. |
Content-Type | Yes | application/json |
Body
A single JSON object.
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | Yes | Must be a valid email address. This is where the review requests go. |
name | string | No | Used for {{customer_name}} in your emails. Omit it and the greeting has an empty name. |
locationShortId | string | No | The short ID of the location this contact belongs to. Omit it and the fallback location is used. |
Example body:
{
"email": "customer@example.com",
"name": "Sarah de Vries",
"locationShortId": "a1b2c3"
}
Example call
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"}'
Replace the URL and the secret with the values from General Settings.
The location short ID
The short ID is the last part of a location's review link, https://my.trustaroo.app/response/{shortId}. Copy it from that location's review link. See Share your review link.
Sending it matters if you run several locations, because the contact's review URL, and therefore the rating you collect, is attached to that one location. A short ID that does not belong to your business profile is ignored, and the fallback location is used instead.
If the request has no usable locationShortId and General Settings has no Fallback Location, the contact cannot be created and the request fails. Set a fallback location before you connect anything.
A successful request
A success returns 200 OK with the new contact's identifier:
{
"id": "3f1b0f9e-0c2a-4b7d-9a52-6f7f2b8c1d34",
"message": "Contact added to automation queue"
}
At that moment the contact:
- appears in the Contacts Queue with the status Pending
- is attached to the resolved location
- has its own review URL of the form
https://my.trustaroo.app/response/{locationShortId}?contact={contactId} - is waiting for step 1, which is sent once its delay has passed
Nothing is emailed by the request itself. A background job checks the queue every 15 minutes and sends whatever is due, so a step with a 0-day delay arrives within about a quarter of an hour.
A rejected request
| Status | Meaning | Fix |
|---|---|---|
400 "Automation not enabled" | Automation is switched off, or this business profile has no automation configuration yet. | Switch on Enable automation and select Save Settings. |
401 "Invalid webhook secret" | The X-Webhook-Secret header is missing or does not match. | Copy the secret again with the Copy button and check for stray spaces. |
400 "Invalid email address" | The email value is not a valid address. | Check the field mapping in the sending system. Sending an empty value is the usual cause. |
500 "Internal server error" | The contact could not be created. No location could be resolved is the common reason. | Set a Fallback Location, or send a locationShortId that belongs to your business profile. |
A rejected request adds nothing to the queue, so it is safe to fix the cause and send it again.
Duplicate contacts
Trustaroo matches on email address within your automation configuration. If that address is already in the queue, the request succeeds and returns the existing contact instead of creating a second one.
That protects you from a Zap that fires twice, but it has a consequence worth knowing: a returning customer who is already Completed or Unsubscribed will not start a new sequence. To ask that person again after a later visit, remove them from the Contacts Queue first, then send the request again.
Practical notes
Trigger on real transactions. One request per completed sale, booking or job. The webhook has no batching and there is no list upload anywhere in Trustaroo.
Keep the secret private. The URL and the secret together are enough to add contacts to your queue, so keep them in your integration's credential store, not in client-side code or a shared document.
Retry politely. If your integration retries after a network error, the duplicate check means a repeated request will not create a second contact.
Test with your own address. Add yourself, watch the contact appear as Pending, then complete a rating through the link in the email you receive. That confirms both directions in one pass.