Skip to content

Setup and Use

Overview

The PracticeERP webhook system allows users to set up webhooks to call external system all from the UI (no code). The webhooks are REST (POST) "ping only," letting the external system know that a record has been created, edited, or deleted, identified by its internal ID.

The system uses several custom records which can be found here: Customization > Lists, Records, & Fields > Record Types.

If you need help setting up the webhook system, please reach out the practiceERP team.

Setting up the system

Create a new Webhook Endpoint record

This record contains details related to the external API endpoint the webhook will ping, and can be reused to define multiple webhooks that use the same endpoint.

  • Name: Give the record a helpful name, for example, SystemX New Customer Endpoint.
  • URL: Enter the full URL of the external API endpoint to ping with the webhook.
  • External System: Select the external system this webhook pings. This is just to help keep things organized and searchable. The selections come from the custom list Webhook External System, and values can be added here: Customization > Lists, Records, & Fields > Lists > Webhook External System.
  • Bearer Token (stored on an API Secret Record ID): The webhooks authenticate with external systems using a bearer token. Populate the internal ID of the API Secret record containing the bearer token record here. To create a new API Secret record, go to: Setup > Company > API Secrets.

Create a Webhook Definition record

Decide if you want to create a User Event Script-based or a query-based webhook, and select the appropriate custom form on the new record. Either option will include these fields:

  • Name: Give the record a helpful name.
  • Endpoint: Select which external endpoint this webhook will ping.
  • Documentation: Make some helpful notes about this webhook.
  • Test Call Body JSON: Hardcode test JSON to send to the external system. In view mode, click the button send text call to send a test webhook containing this payload. Example field contents: { "recId": 1234 }.

UE-based

  • Action: Which record action does this webhook represent (create, edit, or delete)?
  • Transaction/Record Type: The internal ID of the transaction of record type, for example, salesorder or customer.
  • Call Body JSON: The JSON to be send in the webhook call body. The text REC_OR_TRANS_ID will be replaced by the actual numerical transaction/record internal ID. Example field contents: { "recId": REC_OR_TRANS_ID }.
  • Immediate Call: Check this box to send the webhook right when the action occurs. This is the main feature of a UE-based webhook, allowing the webhook to be sent synchronously. If this checkbox is not checked, the system will create a custom record representing a webhook call to be made, which will be picked up and sent by the PRAC API Webhook Calls MR script (max frequency every 15min).

In addition to setting up a new Webhook Definition record, the PRAC API Webhook General UE script must be deployed to the relevant transaction record type.

A limitation of UE-based webhooks is that one UE script cannot trigger another, for example, if a user event scripts on a custom record edited the email address on a vendor record, that vendor record could not be tracked by the UE-based system. There are ways around this behavior, but they would require custom code. Please reach out to the practiceERP team for more information.

Query-based

Create a new Webhook Query Run record.

  • Name: Give the record a helpful name.
  • Base type is Transaction: If the relevant record is a transaction (for example, an invoice, as opposed to a customer), check this box.
  • Transaction/Record Type: The internal ID of the transaction or record type, for example, salesorder or customer.
  • Created Date Field: Different transactions/records can hold their created date in different fields. Check the Records Catalog (Setup > Records Catalog) and make the appropriate selection.
  • Last Modified Date Field: Different transactions/records can hold their last modified date in different fields. Check the Records Catalog (Setup > Records Catalog) and make the appropriate selection.
  • Webhook Definition (Create/Edit/Delete): Select the relevant Webhook Definition record.

In addition to setting up a new Webhook Query Run record, a new deployment of the Webhook Query Run MR must be created, and the Query Run record selected in the script parameter. A schedule must also be set up on this deployment. Every 15 minutes (maximum frequency for map/reduce scripts) is a good choice.

To reset a query run record's memory, click Edit, check the Reset Last Run and Stored IDs checkbox, and save. Upon save, only changes after the new Time of Last Run will trigger a webhook.

How the system works

When a webhook definition detects a relevant action, a new Webhook Call record is created. This record represents a ping to be made to an external endpoint. The calls are made by the PRAC API Webhook Calls MR script, which allows the concurrency to be controlled. Call records are sent in chronological order based on the field Record Creation Request Timestamp, so the recommended concurrency setting on teh deployment is 1. The schedule of the calls can be adjusted on the deployment for this script. If necessary, this MR script could be run on demand, by using Save & Execute.

The call record

  • Status: Pending (before any call has been made), Success (call made), Fail-Retry, and Fail-Final.
  • Error Message: If the status is a fail, the error message will be shown here.
  • Definition Record: This is the webhook definition that created this call.
  • Record Creation Request Timestamp: This timestamp makes sure calls are made in the order in which the event happened (cannot go off creation time, in case one call record is created fast and another very slowly).
  • Transaction/Record Internal ID: The internal ID of the relevant record. This number gets inserted into the JSON of the ping.
  • Error code: The specific error code returned by the external system after a ping.
  • Retry count: The number of retries that have been made for this call. The limit of retries is set in the system library file (currently set to 4). The retries happen using a "backoff" series of time increments in minutes, also set in the system library file (currently 15, 60, 120, 1440). If all the reties result in failure, a status of Fail-Final will be set.
  • Next Call Time: After this time, the next run of the Calls MR script should try to send this ping again.
  • Try again: Do not wait until the Next Call Time, send this ping again the very next run of the Calls MR. This can also be used to retry call records that have reached a Fail-Final status.

A saved search could be set up to catch call records that have reached a Fail-Final status.

System cleanup

After call record is processed successfully, there is no need to keep it around forever. Call records with a status of Success will be deleted after a number of days, as specified in the library file (currently 30). Calls are deleted by the script PRAC API Webhook Delete Calls, which runs one a day.

Error handling

All scripts errors in the webhooks system are logged and a saved search could be set up to monitor them.

System Components

Scripts

CS

  • PRAC_API_WH_DefinitionRecord_CS.js
    • No rec/deploy -- module only

UE

  • PRAC API Webhook Definition Record UE
  • PRAC API Webhook General UE
  • PRAC API Webhook Query Run Record UE

MR

  • PRAC API Webhook Calls MR
  • PRAC API Webhook Delete Calls
  • PRAC API Webhook Query Run MR

SL

  • PRAC API Webhook Send Test Call SL

LIB/Module

  • prac-api-webhooks.js

Custom Records

  • Webhook Call
  • Webhook Definition
  • Webhook Endpoint
  • Webhook Query Run

Custom Lists

  • Webhook Action Type
  • Webhook Call Status
  • Webhook Created Date Field
  • Webhook External System
  • Webhook Last Mod Date Field