Using Webhooks with MoveIN Process Automation

1. What is a webhook?

A webhook lets MoveIN automatically send data to another system when something happens in your instance.

Instead of regularly pulling data from MoveIN (for example by exporting CSVs or running API calls on a schedule), webhooks push information out in real time when a defined event occurs.

Typical use cases

You can use webhooks to:

• Notify your CRM when a lead or contact is updated

• Send application or interview status changes to another platform

• Trigger a scoring process or update a portal account in a third‑party system

In practice, when a rule in Process Automation is triggered, MoveIN calls a URL you provide and sends the relevant data (for example contact, application or lead identifiers).

---

2. How webhooks work (high-level)

1. Create a webhook configuration
   In System Admin > Webhooks, you define:

   • An internal name

   • An event name

   • A target URL

   • A security token

2. Use the webhook in a Process Automation rule
   In Admin > Automation, add a Webhook action to a rule and select which webhook to call.

3. MoveIN sends a POST request
   When the rule conditions are met, MoveIN sends an HTTP POST to your URL with:

   • Object IDs (contact, application, lead, etc., where available)

   • The event name

   • A UTC timestamp

   • The process automation rule ID

   • The token

4. Your system processes the event
   Your system verifies the token, reads the payload and performs the required actions (update records, trigger workflows, call your own APIs, etc.).

---

3. Prerequisite: Webhooks package

The Webhooks module is only available if the webhook package is enabled for your instance.

• If the package is enabled:

  • A Webhooks module appears under Admin > System Admin.

  • You can create and manage webhook configurations.

  • In Process Automation, the Webhook action shows the list of configured webhooks.

• If the package is disabled:

  • The Webhooks module does not appear in System Admin.

  • In Process Automation, the Webhook action may still be visible, but:

    • An error message is displayed to indicate the webhook package is missing.

    • The webhook list is hidden so it cannot be used.

If you do not see the Webhooks module and believe you should, contact your MoveIN administrator or your account manager.

---

4. Managing webhooks in System Admin

4.1. Webhooks grid

Once the package is enabled, go to:

Admin > System Admin > Webhooks

This opens a grid similar to other admin grids (for example: https://demoschool.mymovein.com/#system-admin/label_group).

The grid contains:

• Default columns

  • Name – unique internal name of the webhook

  • Event Name – descriptive label for the event

• Attributes and actions

  • Webhook attributes (for example Active/Inactive, audit‑related fields)

  • Create New button

  • Copy and Delete options

  • Sort By options

4.2. Permissions (roles and rights)

Access to create, edit, copy and delete webhooks is controlled through roles and rights.

To configure this:

1. Go to Admin > Roles and Rights > Administration.

2. Locate the Webhook module.

3. Use the checkboxes to grant or revoke:

   • New

   • Copy

   • Edit

   • Delete

Only users with the appropriate rights will see these options in the Webhooks grid.

4.3. Creating a new webhook

1. Go to Admin > System Admin > Webhooks.

2. Click Create New.

You will see a form with the following fields:

• Name

  • Text field, accepts all characters.

  • Must be unique (duplicates are not allowed).

• Event Name

  • Text field, accepts all characters.

  • Describes the event that will trigger the webhook (for example: Lead Source updated).

  • Sent in the payload to help your system understand what happened.

• Token

  • Text field, accepts all characters.

  • Works as a secret key to validate that the request comes from MoveIN.

  • This value is sent as an HTTP header.

  • Generate and store this securely on your side.

• Event URL

  • Text field that must be a valid URL (for example: https://example.com/hooks/movein).

  • MoveIN will send POST requests to this URL whenever the webhook is triggered.

Additional behaviors:

• Active / Inactive status
  Webhooks can be configured with an Active or Inactive status (similar to API configurations).

  • If a webhook is Inactive, MoveIN does not send any data for it.

• Delete protection
  If a webhook is currently used in a Process Automation rule:

  • Users are not allowed to delete it.

  • This prevents breaking existing rules.

---

5. Using webhooks in Process Automation

5.1. Adding a webhook action to a rule

To call a webhook from an automation rule:

1. Go to Admin > Automation.

2. Create a new rule or edit an existing one.

3. Configure the Main Object and the When condition as usual (for example:

   • Main Object: Contact, Application, Interview, Deposit, Lead Source, Scoring, Portal Account, etc.

   • When: Field‑based triggers or time‑based triggers).

4. In the Action section, open the dropdown and select Webhook.

5. A dropdown appears listing all Active webhooks configured in the system.

6. Select the webhook you want to call when the rule fires.

7. Save the rule.

Important behaviours:

• The Webhook action appears in Automation only when the webhook package is enabled.

• If the instance does not have the package:

  • The Webhook action remains visible, but an error message is displayed.

  • The list of configured webhooks is hidden.

5.2. Example scenarios

Below are typical scenarios that have been tested:

Example 1 – Interview trigger

• Main Object: Interview

• Condition: Interview remark = spider

• Action: Webhook → Select your Interview webhook

When the Interview remark is set to spider, MoveIN sends the webhook POST request.

Example 2 – Deposit bulk update

• Main Object: Deposit

• Condition: Deposit status = Paid

• Action: Webhook → Select your Deposit webhook

When Deposit forms are submitted and marked as deposit "Paid", MoveIN sends one webhook call per matching record.

Example 3 – Lead Source bulk update

• Main Object: Lead Source

• Condition: Lead Source Recruitment Manager updated to a specific value

• Action: Webhook → Select your Lead Source webhook

When you bulk update Lead Source RM, MoveIN sends a webhook call per updated record.

Example 4 – Time-based Contact follow-up

• Main Object: Contact

• When: Time-based (based on a date field or a fixed date)

• Action: Webhook → Select your follow‑up webhook

After the configured date/time passes, MoveIN sends the webhook call.
There can be a delay (for example 10–15 minutes) due to batch processing. This is expected behaviour for time‑based rules.

---

6. Data sent in the webhook (for developers)

This section is intended for technical readers who will consume the webhook in their own systems.

6.1. Transport details

• HTTP method: POST

• Client library: MoveIN uses Guzzle in the backend to send requests.

• Target URL: The Event URL configured in the webhook.

• Authentication:

  • The configured Token is sent in an HTTP header.

  • Your service should verify this token before trusting the request.

6.2. Payload structure

When a webhook action runs, MoveIN:

1. Executes an internal action ActivityWebHook.php.

2. In the run() function, it collects the following data (when available):

   • contactId

   • applicationId

   • scoringSheetId

   • leadId

   • processAutomationRuleId

   • token

   • utcTimestamp (UTC timestamp of the event)

   • eventName (from the webhook configuration)

3. This data is added to a platform message and sent as a long task 

   $this->getMessage()->addAction('moveinLongTask', 'send', $data, WebHookPost::Class);

   The WebHookPost service module’s send() method:

• Uses Guzzle to send a POST request to the configured URL.

• Sends the token as a header.

• Sends the rest of the data in the request body.

Recent changes ensure the body is JSON‑encoded. A typical JSON payload looks like:

{ "contactId": "60ddd7a2757298560063fee2", "applicationId": "60ddd7c359d19f3b0107e8a2", "scoringSheetId": null, "leadId": "1234567890", "processAutomationRuleId": "60ddc3c4ec9e50636f4ca542", "token": "YOUR_SECRET_TOKEN", "utcTimestamp": "2021-07-01T12:34:56Z", "eventName": "Lead Source updated" }

1. Token header example (header name can be agreed with your implementation; a common pattern is):

2. X-Movein-Token: YOUR_SECRET_TOKEN Content-Type: application/json

    

   Object‑dependent IDs

1. The set of IDs present in the payload depends on the Main Object of the automation rule and the trigger context:

   • leadId is only present when Lead Source is used as the main object in automation.

   • If Application is the main object, leadId is not included (this was confirmed during QA and is expected behaviour).

   • Other IDs (contactId, applicationId, scoringSheetId) can be null if they do not apply to the current context.

   ---

   7. Audit log and status

1. To help with monitoring and troubleshooting, webhooks maintain an internal audit log.
   Each log entry can include fields such as:

   • id

   • webhookId

   • postStatus (for example: success / failure)

   • automationId

   • errorReason

   • date

   This allows MoveIN support and your technical team to see:

   • When a webhook was triggered

   • Whether the POST request succeeded

   • Any error codes or reasons recorded

   ---

   8. Testing your webhook

   8.1. Using webhook.sit

   A simple way to test your configuration is to use a public test tool such as:

   URL: https://webhook.site/

   Steps:

   1. Go to https://webhook.site/.

   2. Copy the unique URL it generates (for example https://webhook.site/#!/1234-...).

   3. In Admin > System Admin > Webhooks, create a webhook and use this URL as the Event URL.

   4. Configure an automation rule that triggers this webhook.

   5. Perform the action in MoveIN (for example updating an Interview or Deposit as per the rule).

   6. Look at https://webhook.site/ to see the incoming requests.

   Notes:

   • You may need to refresh the page on webhook.site to see new entries.

   • External tools like this may introduce slight delays. This does not indicate an issue with MoveIN.

   Once you confirm the configuration works, replace the Event URL with your own staging or production endpoint.

   ---

   9. Best practices and known limitations

1. 9.1. Best practices

1. • Use meaningful names
     Example:

     • CRM – Lead created

     • Data warehouse – Application updated

   • Secure your endpoint

     • Validate the token header.

     • Consider IP allowlisting, rate limiting and additional application‑level checks.

     • Log all incoming webhook calls on your side.

   • Design for retries and duplicates

     • Make your handler idempotent (for example, check if you already processed a combination of IDs + timestamp before applying changes).

     • Treat time‑based or external delays as normal and safe to retry.

   • Choose the right main object

     • The main object controls which IDs you receive.

     • Use Lead Source as main object when you specifically need leadId.

     • Be aware that certain IDs will be null if they are not applicable.

   9.2. Expected behaviours / limitations

1. • Time‑based rules

     • Time‑based triggers can fire with a delay (for example 10–15 minutes), due to batch processing.

   • External testing tools

     • When posting to third‑party websites (such as https://webhook.site/), visible delays or the need to refresh the page are related to those tools, not to MoveIN.

   • Lead ID availability

     • leadId is only present when Lead Source is used as the main object in automation.

     • It is not available when Application is used as the main object (this was validated during QA and is working as designed).