Webhooks
Webhooks allow for you to get push notifications from the system based on specific events when they happen. That information is sent to a URL which you specify. This is an alternative approach to standard the polling method, where you periodically submit requests for updates. The webhooks can be configured in the webhooks tab of your project settings.
It is important to note that API activity will not activate the webhooks. For instance, if I am using create (an API action) to create a user, user_registered (a webhook event) will not fire. Additionally, the system will confirm the presence of an API admin within a project prior to sending the webhook data.
An API admin is able to configure a webhook by logging in the back end, navigating to settings, project settings, and clicking the webhooks tab. From here, simply choose your event and enter the URL where you would like the information sent. Note that only one event can correspond to a single URL.
Each webhook will always return both user_info and meta_info.
On events which include a wildcard * you are expected to replace the wildcard with the form id. This enables you to receive an event only when it happens for that specific form. Any additional returns are show below and are specific to the webhook response:
Name | Return | Description |
|---|---|---|
user_registered | - | This fires the first time an applicant registers. |
login_success | - | This fires each time the user logs in. If the user requested the system remember them then if they are granted access through this mechanism this webhook will not fire. |
edit_user_credentials | username only (generally an email). password is not included. | This fires when an applicant edits their username or password. |
form_submitted | form_info, which contains meta-information about the form which was submitted. doc which will include all fields and their values for that user's form. Will also return google or Facebook analytics. | This fires each time a form is submitted, irrespective of the forms completion status. It is less advised to use this to gather information about a user, since it will fire on every form which is submitted. Instead see the wildcard option below. |
form_submit_* | Returns form_info after form is submitted. Responding with msg and msg_type (error, notification, warning, success, information) can allow you to display error handling and/or manipulate form information by returning a jdoc obj. Can use focus_on to focus on a specific field. Can redirect to a valid URL. | Similar to form_submitted however it will fire only when your specified form is submitted. |
form_load_* | doc | This event occurs when a user accesses the specified form regardless of any future actions by the user (when the form loads). This is primarily used for redirects. |
form_viewed_* | doc | This event occurs immediately after form_load_*. |
user_complete | Same as form_submitted. | This fires when all user forms are marked complete in an individual system, or when parent forms are complete in a family system. Note that if forms are added as a result of a trigger, the webhook will not fire until those subsequent forms are completed as well. |
child_complete | Same as form_submitted. | Similar to user_complete, except this fires when all child forms are complete. This is only relevant in family systems |
status_update | Returns an array of user_info for each applicant whose status has changed in addition to information about the status. | This fires when a status is changed for either a single user or a group of users. |
payment_event | Includes payment_info, cart_info, and allocated_payments which will show you what payment paid for what item in the cart. | This fires when any payment event occurs, such as payments marking as approved, as pending, being refunded, etc... |
payment_refunded | same as payment_event | This occurs when an admin issues a refund for a user. |
payment_issued | same as payment_event | This occurs when a payment is made by an applicant, or is processed by an admin. |
tag_update | tag_info | This event occurs when either a single user or a group of users has their tag changed. |
user_order_updated | | This occurs when a user adds or removes a product from their cart. |
form_preprocess (all forms) form_preprocess_* (specific form) | Returns form_info before submission is processed. Responding with msg and msg_type (error, notification, warning, success, information) can allow you to display error handling or manipulate form information by returning a jdoc obj. Can use focus_on to focus on a specific field. Can redirect to a valid URL. Note:
| This occurs when a user submits their form before the submission is processed. |
