CONTACT USBack to MinistryPlatform Site
Your Knowledge Base has moved to the new Help Center.  Check out the release notes for details. And don't forget to update your bookmarks and in-house documentation before May 28.

Webhooks

 
Webhooks are created and managed in the Administration folder. Very few Users should have access to these records. Those with access should use extreme caution when adding or editing records.

Basics

  • Webhooks facilitate targeted notifications when specific, pre-defined changes are made. They can be triggered when specific data is created, updated, or deleted. 
  • Webhooks in MinistryPlatform are intended for notification only, it is then up to the receiving software to retrieve the changed data via the REST API and update it's own records accordingly. 
  • To maintain security standards, these webhooks will notify only that a change has taken place. Tokens that reveal the specific changes are not supported in the request and will not render as values in the payload. 
  • Table Lookup Convention is not supported.  
  • Webhooks are Table based, not Page based.

Webhook Fields

  • Display Name*: A short, descriptive title. 
  • Description: A place to add pertinent information such as an overview of how the Webhook will be triggered. 
  • Http Method*: GET or POST
  • Uri Template*: The endpoint where a payload will be delivered. 
  • Body Template: The following tokens are supported using standard JSON formatting (optionally a constant value may also be defined):
    • dp_RecordID
    • dp_UserID
    • dp_AuditType
  • Headers Template: An optional header which may be included in the payload. 
  • Trigger Fields: Fields listed here further qualify what must change on a record to trigger the Webhook. If left blank, changes to any field on the record will trigger the Webhook. Formatting should exclude table names and brackets. Multiple fields can be separated by commas. For example:  Display_Name, Date_of_Birth, Email_Address.
  • Dependent Condition: If the Process should not be invoked for all Records on this Page, specify field values here. Values should be formatted as part of the WHERE clause. For example: __Age >= 18 AND Email_Address IS NOT NULL. Table Lookup Convention is NOT supported. Note: Any records you reference in the Dependent Condition must exist when the Webhook is invoked. For example, let's say a Webhook is triggered on the Form_Response. If the Dependent Condition references a Form_Response_Answer, the Webhook will not trigger because the Form_Response_Answer records may not exist for that Form_Response yet.
  • Trigger On Create*: Set as True/False to determine whether this Webhook should be invoked by newly created records.
  • Trigger On Update*: Set as True/False to determine whether this Webhook should be invoked when the value of a Trigger Field is updated. 
  • Trigger On Delete*: Set as True/False to determine whether this Webhook should be invoked when a record is deleted. 
  • Max Retries*: Define the maximum number of attempts to trigger the Webhook before termination. One attempt will be tried per minute.
  • Active*: Must be true for the Webhook to execute. 

  • Table Name*: The Table to which this Webhook applies. Changes made to records in this Table via the REST api will trigger the Webhook.

Important! If the trigger field is populated as part of a new record creation, the change type displays as "created". If the entire record is deleted, the change type displays as "deleted". If the record exists and the trigger field is populated, updated, or cleared, the change type always displays as "updated". To receive alerts on a field level (for example, email address is erased), set Trigger on Update to Yes.
Tip: Refer to Foreign Keys by their proper field name regardless of how it displays on the record. In many cases, this means appending the field with _ID. For example, to use Marital Status as a Trigger Field on a Contact Record, the proper field would be Marital_Status_ID.

Webhook Invocations

When the Webhook is invoked by creating, updating, or deleting records a Webhook Invocation record is created. 

  • Record ID*: The ID of the MinistryPlatform Record that invoked this Webhook. 
  • Created*: A timestamp indicating when this Invocation was created. 
  • Updated: A timestamp indicating when this Invocation was most recently updated. Initially populated when the first Response is received this will be updated accordingly if retries are attempted. 
  • Status*: The ID of the currently applicable Webhook Invocation Status. 
  • Retries Left*: Displays the number of unused retries. If retries are attempted, this value decrements until it reaches zero. 
  • Uri*: The endpoint where this payload will be delivered. 
  • Body: A rendered version of the Body Template where tokens have been replaced by their values. 
  • Headers: A rendered version of the Headers Template where tokens have been replaced by their values. 
  • Response: A response indicating whether the payload was successfully received. 

Create a Webhook

Below is a step-by-step example of how to create a simple Webhook. 

In this example, the Webhook will be triggered when an Email Address or Mobile Phone are updated on a Contact record. Here's how the Webhook fields might be populated:

  • Display Name: Alert for Basic Contact Info 
  • Description: Notify when a Contact's Email Address or Mobile Phone is added, updated, or removed. 
  • Http Method: POST
  • Uri Template: http://api.sample.com/endpoint/
  • Body Template: {"id": [dp_RecordID], "userid": [dp_UserID], "changetype": "[dp_AuditType]", "tablename": "Contacts"}
  • Trigger Fields: Email_Address, Mobile_Phone
  • Trigger On Create: True
  • Trigger On Update: True
  • Trigger On Delete: True
  • Max Retries: 3
  • Active: True 
  • Table: Contacts

Additional Resources