Webhooks
This section examines using webhooks in MinistryPlatform, including a brief overview, fields, invocations, and information on creating a webhook.
Create and manage webhooks in the Administration folder. Very few people should have access to these records. Those with access should use extreme caution when adding or editing records.
- Webhooks facilitate targeted notifications when someone makes specific, pre-defined changes. They can be triggered when someone creates, updates, or deletes specific data.
- Webhooks in MinistryPlatform are intended for notification only. It is then up to the receiving software to retrieve the changed data through the REST API and update its own records accordingly.
- To maintain security standards, webhooks notify only that a change occurred. The request does not include tokens that reveal the specific changes. These tokens will not render as values in the payload.
- You can't use the Table Lookup Convention.
- Webhooks are based on tables, not pages.
Webhook Fields
Important: If you populate the trigger field as part of creating a new record, the change type displays as "created." If you delete the entire record, the change displays as "deleted." If the record exists and you populate, update, or clear the trigger field, 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.
Note: Refer to foreign keys by their proper field name regardless of appearance on record. In many cases, this means adding "_ID" to the field. For example, if Martial Status is a Trigger Field on a Contact Record, the proper field would be Martial_Status_ID.
- Display Name
- A short and descriptive title.
- Description
- A place to add information such as an overview of how to trigger the webhook.
- 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, you may also define a constant value):
- 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. Use commas to separate multiple fields. For example: Display_Name, Date_of_Birth, Email_Address.
- Dependent Condition
- If you don't want to invoke the process 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. You can't use the Table Lookup Convention. Note: Any records you reference in the dependent condition must exist when you invoke the webhook. For example, let's say a the Form_Response triggers the webhook. 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 Yes or No to determine whether to invoke this webhook with newly created records.
- Trigger on Update
- Set as Yes or No to determine whether to invoke this webhook when someone updates the trigger field value.
- Trigger on Delete
- Set as Yes or No to determine whether to invoke this webhook when someone deletes a record.
- Max Retries
- Define the maximum number of attempts to trigger the webhook before termination. One attempt will be tried per minute.
- Active
- Must be set to Yes for the webhook to work.
- Table Name
- The table to which this webhook applies. If you change records in this table through the REST API, the webhook triggers.
Webhook Invocations
When you invoke the webhook by creating, updating, or deleting records, you create a Webhook Invocation record.
- Record ID
- The ID of the MinistryPlatform record that invoked this webhook.
- Created
- The time this invocation was created.
- Updated
- The time this invocation was most recently updated. This field initially populates when it receives the first response. This field updates accordingly if retries are attempted.
- Status
- The ID of the currently applicable webhook invocation status.
- Retries Left
- Displays the number of unused retries. You can retry until this field reaches zero.
- URI
- The endpoint where this payload will be delivered.
- Body
- A rendered version of the body template where values replace their tokens.
- Headers
- A rendered version of the headers template where values replace their tokens.
- Response
- A response indicating whether the payload was successfully received.
Creating a Webhook
Here's what you need to know to create a simple webhook.
In this example, the webhook triggers when you update an email address or mobile phone on a Contact record. Here's how you might populate the webhook fields:
- 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