API & webhooks
Connect Fairvero to the systems you already use.
Send invitations from your shop or CRM as orders complete, answer reviews from your own tools, and react the moment a review is published.
curl https://api.fairvero.com/api/v1/integration/invitations \
-H "Authorization: Bearer $FAIRVERO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-10482" \
-d '{ "customer": { "email": "[email protected]", "name": "Priya" },
"referenceId": "order-10482",
"productSkus": ["SKU-123"] }'What you can build
Common integrations
Invite after every order
Your shop calls Fairvero when an order is delivered; the invitation goes out at the time you choose.
Reviews in your helpdesk
A webhook on each new review creates a ticket; your team replies from the helpdesk through the API.
Keep catalogue in sync
Push customers, products and locations so invitations and analytics line up with your own data.
Getting started
From key to first request
Create a key
In API & webhooks, name the key and tick only the scopes it needs.
Call from your server
Send it as “Authorization: Bearer <key>”. Never put keys in a browser or app.
Add a webhook
Give an HTTPS address, pick events, and keep the signing secret safe.
Endpoints
What the API covers
All under https://api.fairvero.com/api/v1/integration, JSON in and out.
| Area | Endpoints | Scope |
|---|---|---|
| Business | GET /business | business:read |
| Invitations | POST /invitations, POST /invitations/bulk (up to 1,000), GET /invitations, GET /invitations/:id | invitations:write, invitations:read |
| Reviews | GET /reviews, GET /reviews/:id, POST /reviews/:id/reply, DELETE /reviews/:id/reply | reviews:read, reviews:reply |
| Customers | GET /customers, POST /customers, POST /customers/import | customers:write |
| Orders | GET /orders, PUT /orders | customers:write |
| Products | GET /products, PUT /products | business:read to read, products:write to change |
| Locations | GET /locations, PUT /locations | business:read to read, locations:write to change |
Webhooks
Know the moment something happens
Choose the events each endpoint receives. Every delivery is a signed POST with a JSON body.
| Event | Sent when |
|---|---|
review.created | A customer submits a review (before checks). |
review.published | A review passes our checks and becomes public. |
review.updated | A review changes, for example the author edits it. |
review.reply.created | Your team posts a public reply. |
invitation.created | An invitation is created. |
invitation.completed | The customer wrote a review from the invitation. |
business.updated | Your public profile changes. |
Security
Check that a webhook really came from us
Every delivery has three headers:
| Header | Use |
|---|---|
fairvero-signature | t=<unix time>,v1=<hex>: HMAC-SHA256 of t + "." + body with your endpoint’s secret. |
fairvero-event-id | The same for every retry of one event: use it to skip duplicates. |
fairvero-delivery-id | Unique per delivery attempt, for your logs. |
Reject requests whose timestamp is more than 5 minutes old.
import { createHmac, timingSafeEqual } from 'node:crypto';
// header: the "fairvero-signature" request header, body: the raw request body (string)
export function isFromFairvero(secret, header, body) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes
const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
const given = String(parts.v1 ?? '');
return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}Questions
For developers
Which plans include the API?
Growth and Pro. API keys and webhooks are created under “API & webhooks” in your dashboard.
How do I avoid sending the same invitation twice?
Send an Idempotency-Key header (for example your order number). Repeating the request with the same key returns the first invitation instead of creating another.
What if my server is down when a webhook is sent?
Failed deliveries are retried with increasing gaps for about a day. Each delivery carries a fairvero-event-id header, so you can ignore one you already processed.
Can one key access several businesses?
No. A key belongs to one business and only reaches that business’s data, with the scopes you chose when creating it.