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
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