Use a webhook automation to send data from Vizmo to your own web address whenever a selected event happens at a location, for example when a visitor is created or updated.

Before you start

• You need a location admin or company admin account that can use Automation. The menu is not shown to employee or front-desk accounts.
• Have the web address (URL) of the service that will receive the data.
• The Visitors and Invites modules are always listed. Desks, Rooms and Digital Registers appear only when that product is turned on for the location.
• Availability: if this option is greyed out or missing, contact your Vizmo account manager.

Add a webhook

1. Sign in to the Vizmo portal, select the location and open Automation > Workflows.
2. Select Create.
3. In the New Automation panel, enter a Workflow Name, choose a Module, set Type to Webhook and choose an Event (Created or Updated).
4. Select Add Condition if the webhook should run only for some records, then select Next.

5. On the Edit Webhook tab, enter the URL of your service.
6. Add URL Parameters or Request Headers with the + buttons if your service needs them.
7. Under Body, choose what to send:
   • Default Payload sends the standard event details in JSON format.
   • Form Data and x-www-form-urlencoded send the fields you add.
   • Raw sends text, JSON or XML that you write yourself. Use Insert Placeholder to add details from the event, such as the visitor's name.

   The Content-Type header is set for you from the Body type and cannot be edited.

8. If your service checks signatures, select I want to secure this webhook and enter a Secret. Store the same secret on your service.
9. Select Save.

To change a webhook later, open it from the Workflows list, make your changes and select Save. A webhook runs as soon as the selected event happens and the conditions match.

To stop a webhook, delete it. There is no option to pause one. Open the webhook and select Delete, or select the bin icon on its row in the Workflows list, then confirm. If you do not see Delete, your role may not allow deleting automations.

What your service should do

• Reply with a 2xx status once the data is received.
• If your service replies with a server error (a 5xx status), Vizmo tries again.
• If your service replies with a 4xx status, Vizmo does not try again, because it treats that as a problem with the request.

Verify the signature

When I want to secure this webhook is selected, every request includes the header X-Vizmo-Secret. Its value is sha256= followed by an HMAC-SHA256 hash of the request body, written in lowercase hexadecimal. The hash uses your secret as the key. The secret itself is never sent.

Note: the hint under Secret in the webhook form names the header X-Vizmo-Signature. Vizmo sends X-Vizmo-Secret, so look for that header.

1. Take the body exactly as you received it.
2. Calculate its HMAC-SHA256 hash with your secret.
3. Add sha256= in front of the result.
4. Check that it matches the X-Vizmo-Secret header.

For example, in Node.js:

const crypto = require("crypto");
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");

Note: To check the body exactly as received, set the Body to x-www-form-urlencoded or Raw with the type Text or XML. With Default Payload, Form Data or Raw with the type JSON, the body can be laid out slightly differently from the text that was signed, so the hash of the received body may not match.

Troubleshooting

• Your service is not called. Check that the workflow is saved, the event matches and any conditions are met. Make sure the URL can be reached from the internet. Open Automation > Logs, or the Executions tab of the workflow, to see whether it ran.
• Signature check fails. Look for the X-Vizmo-Secret header, confirm the secret is identical on both sides and compare the complete value including sha256=. Then see the note above about body types.

To send an email or webhook after an approval, see Run an email alert or webhook after an approval. For email alerts, see Create an email automation.