Connect Vouchfield
to your other tools.

Before you start

• An API key. The workspace owner makes one in Settings → API keys. It is shown once, so copy it straight away.
• A Zapier or Make account.

Part 1. Get a message when an audit finishes

1. In ZapierMake a new Zap. For the trigger, pick Webhooks by Zapier, then the event Catch Hook. Copy the address Zapier shows you.
2. In MakeMake a new scenario. Add the Webhooks module Custom webhook, click Add, give it a name and copy the address Make shows you.
3. Give that address to VouchfieldIn your workspace, open Settings → Webhooks, paste the address and save. Only the workspace owner can do this. The address must start with https://.
4. Choose the eventsOn the same page, tick An audit finished. Tick An audit failed too if you want a message when an audit could not finish, for example because we couldn't reach the website.
5. Send a test messageOn the same page, click Send a test message. It arrives within about a minute, with the event webhook.test. It is not an audit, so it has none of the audit fields.
6. Wait for a real audit to finishRun one audit. Use its message as the sample: in Zapier, click Test trigger; in Make, run the scenario once while it waits for data.
7. Map the fieldsPick the fields you need, such as business.name, score and report_url. The full list is below.

Example request. You can send it from a terminal, from an API tool such as Postman, or from a one-off Zapier or Make HTTP step.

curl -X POST https://vouchfield.com/v1/scan \
  -H "Authorization: Bearer YOUR_MAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "yourclient.com", "webhook_url": "PASTE_THE_ZAPIER_OR_MAKE_ADDRESS_HERE"}'

What the message contains

Vouchfield sends a POST with a JSON body. The body is the same as GET /v1/scan/{id}.

A test message from Settings → Webhooks has the event webhook.test, the same headers and signature, and always this body:

{"event": "webhook.test", "test": true, "message": "This is a test message from Vouchfield. It is not an audit."}

Part 2. Call the Vouchfield API from Zapier or Make

1. Add an HTTP stepIn Zapier, add the action Webhooks by Zapier, then Custom Request. In Make, add the HTTP module Make a request.
2. Point it at the APIUse the address https://vouchfield.com plus the endpoint, for example https://vouchfield.com/v1/scan/ followed by the id from the message.
3. Add your keyAdd one header. Name: Authorization. Value: Bearer, a space, then your API key.
4. Send JSON when you start an auditFor POST /v1/scan, set the body type to JSON and send at least url. Add an Idempotency-Key header with a value that is unique to that row or record. If Zapier or Make retries the step, you won't pay for a second audit.

The full notes are at /v1/docs.

Two simple recipes

1. Finished audit to a spreadsheetTrigger: the catch hook above. Step 2: GET /v1/scan/{id} with the id from the message. Step 3: add a row with business.name, url, score and report_url.
2. New row to a new auditTrigger: a new row in your sheet or a new deal in your CRM. Step 2: POST /v1/scan with the website from that row. When the audit finishes, the catch hook above picks it up.

Good to know

• Which audits send a message: every audit for your agency that finishes, whether you started it in your workspace, through your website widget or through the API. An audit that fails sends a scan.failed message only if you ticked An audit failed. If we couldn't reach the website, credit_returned tells you whether the credit came back.
• One address per agency. To change it or stop the messages, open Settings → Webhooks in your workspace. Removing the address cancels messages that have not been sent yet. You can also set it with webhook_url when you start an audit through the API with your main key.
• Checking messages: each message is signed. The workspace owner can reveal the signing secret in Settings → Webhooks. Replacing it there stops the old secret at once. Zapier's and Make's catch hooks can't check the signature, so treat the message as a tip-off. Before you act on it, fetch the audit with GET /v1/scan/{id} and your key. Only your own API keys can read your audits.
• Test messages: X-Audit-Event is webhook.test and the body is always the small JSON shown above. Skip it in your Zap or scenario, for example with a filter on the test field.
• Delivery log: Settings → Webhooks shows the last 10 messages, the answer your address gave and how many tries it took. Open a message to see every try, and click Send again to send a finished message once more.
• If your address keeps failing: after 3 messages in a row fail every try, we switch webhook messages off and email the workspace owner. Fix the address, then click Turn messages back on in Settings → Webhooks.
• Retries: your catch hook must answer within 10 seconds with a success code. If it doesn't, we try again after about 1 minute, 5 minutes, 25 minutes and 2 hours, then stop. Zapier and Make answer straight away, so this is rare.
• Keys: give Zapier or Make its own key. Make one in Settings → API keys (or with POST /v1/seats and your main key). You can switch that key off, or replace it, on its own. That key can start and read audits.
• Speed limit: each key can make 120 requests a minute. Beyond that the API answers 429 with a Retry-After header saying how many seconds to wait.
• Plans: Webhooks by Zapier and Make's webhook and HTTP modules are Zapier and Make features. Check that your Zapier or Make plan includes them.