In SiteCapture you can configure a webhook which will send an HTTP request to a specific URL anytime your SiteCapture projects enter a particular workflow state. This is particularly useful for integrations; for example: the transfer of data from SiteCapture to another system might be triggered when projects enter the COMPLETE workflow state.
Creating A Webhook
1. Under the gear icon, select App Integrations.
2. On the integrations page, select: SiteCapture Webhook on Project Status Event.
3. Click the Configure button, and then Next.
4. Complete the form, providing your SiteCapture username and password (Portal Admins only), and your Webhook URL.
5. It's possible to receive the webhook for ALL statuses, including those that don't have an associated workflow state. Click the button to the right (On).
6. If you'd like to receive notifications only for specific workflow states, click the button to the left (Off). Click the “Add to Send the webhook for specific workflow states” button and then choose a workflow state. Repeat this to include all desired workflow states.
7. If you would like to validate the incoming webhook requests, copy the “HMAC Shared Secret” for later. (See below).
8. Click Finish.
9. If you need to reconfigure the webhook, pause the integration, or deactivate the integration you can do so after clicking on the "SiteCapture Webhook on Project Status Event".
How It Works
Once you have created your webhook, an HTTP request will be sent (via POST) to your configured URL. The body of the request will look like this:
{
"project_id": 3057,
"status": "Complete",
"workflow_state": "COMPLETE",
"api_key": “your_api_key”,
"event": "status_change"
}
Validating a Webhook Request
There are two pieces of information sent in each webhook request to help validate that the request has been sent by SiteCapture and not some other party:
- Your API key is included in the request body
- An encoding of the request body is included in an HTTP header called x-hmac-hash
With (1), you can validate that the incoming key matches your SiteCapture API key.
With (2), you can calculate an HMAC signature using the incoming request body (JSON) and the “HMAC shared secret” that is visible in the Webhook configuration screen, as described above. This can be done programmatically or using a tool such as this one:
Comments