Webhooks have been added as a feature which will allow customers to do more with data.
This could be utilized by customers who are building custom integrations and need to know when an event is triggered (e.g. Salesforce/NetSuite or other custom development). Ability for an organization to receive event(s) at a customer-configured endpoint. The set of events would be configurable. The endpoint could be authorized. Payloads would be predetermined and not configurable.
They can be configured from a new “Webhooks” tab available on the organization.
In order to give access to a user to access to see/add/modify webhooks, they’ll need the Org.webhooks permission (see below)
- When creating a Webhook, you will need to fill out the following items:
- Name
- Webhook URL
- Webhook Authentication Methods
- You can use No Auth or Basic Auth (depending on the receiving system).
- Events to send, there are a number of different events and types which are organized by kind:
- Job Events
- Created - When the job is created
- Updated - When the job is updated
- Assigned - When the job is re-assigned to a different user
- Image Created - When an image is created on the job
- Document Created - When a document is created on the job
- Status Changed - When the status changes on the job
- Estimate Events
- Created - When the estimate is created
- Updated - When the estimate is updated
- Signed Document Events
- Signed - When the signed document is signed by all parties
- Signable Document Events
- Signed - When the signable document is signed by all parties
- Job Events
Note: When adding a webhook the URL MUST be https as we do NOT send webhooks to non-secure URLs.
- Once you’ve created a webhook, you’ll be taken back to the webhook listing where you can view a list of the webhooks and check the status. By default, when you create a webhook, it will be in a “deactivated” state. To turn it on, simply toggle the toggle button to the on position.
- Once you’ve toggled it to the On position, the system will then generate a payload to your endpoint.
- Debugging webhooks is also supported on this screen. To access or edit the webhook, click the pencil next to the specific webhook to bring back up the detail screen.
- On the detail screen, there is a section called “Log History” which will include all of the Webhook events which are generated for this webhook.
- For each of these items, the following information is there:
- ID - The internal id of the event sent to the system
- Date/Time - The date/time the event was created
- Event - The type of event (Job Created, etc.) which was sent
- Webhook URL - The endpoint which was called
- Response - The latest response returned from the receiving URL (HTTP status code)
- You’ll also notice there is an expand icon which is available to view details.
- The Log History Modal also has additional information if the expand icon is clicked:
- ID, Event, and Webhook URL same as the previous screen
- The payload is also present which includes the full JSON payload of all the data included in the webhook.
- Webhook Attempts - The system expects to receive an HTTP 2xx response when it sends a webhook to the URL.
- If the system does NOT receive a 2xx response, it will retry again in 5 minutes.
- If it fails again in 5 minutes, it will attempt again in 10 minutes.
- At the point it has failed 3x it will not retry again.
- For each of the attempts, the system logs the status, date, time, and response code returned from the endpoint which was called.
- To find more details out about each attempt, you can click to expand the accordion next to each attempt to expose the Response Code, Response Headers, and Response Body for each attempt.