Webhooks: tell your own system when something changes

A webhook sends a signed message to your own address when a plan is created or saved, an export is ready or a measuring report is ready.

This needs Pro.

Webhooks: tell your own system when something changes: step by step

1. 1. Open Settings, API

   Webhooks sit under the API keys. You need to be owner or admin of a workspace with Pro or Team.

2. 2. Add a webhook

   Type an https address, pick the events and click Add webhook. Copy the signing secret: we show it only once.

3. 3. Check the signature

   Every message has the header Squaremetry-Signature with t (the time) and v1, the HMAC-SHA256 of "t.body" with your secret. Refuse a message when it does not match or when t is older than 5 minutes. The developer page has an example.

4. 4. Skip doubles

   Squaremetry-Event-Id stays the same on every try and on Send again. If you saw the id before, answer 200 and do nothing.

5. 5. When your system is down

   Anything but a 2xx answer within 10 seconds is tried again after 1, 5 and 30 minutes, then 2, 6, 12 and 24 hours. After 8 tries we give up; after 20 given up in a row the webhook switches itself off.

6. 6. Test, switch off, new secret

   Send test event sends a ping. Last deliveries lists what was sent, with Send again. New secret replaces the secret at once. When Pro or Team ends, the webhooks show as Paused: nothing is sent, and you can only switch them off or remove them until the plan is back.

Messages you may see

• Use an address that starts with https://.
• This address is in a private network. Use a public address.
• Switched off after 20 failed deliveries in a row. Fix the address, then switch it on.

Related

• API keys
• Export a 3D model or a BIM file (GLB, USDZ, OBJ, IFC)