Legacy Webhooks

Zyllem's legacy webhooks (aka manual webhooks) allow you to receive real-time updates from Zyllem, based on 3 types of events that occur in your enterprise. An important thing to note about legacy webhooks is that they require configuration through the web portal.

Legacy webhooks support the following events:

Event TypeDescription
Item AssignmentOccurs when an item is assigned, reassigned, or unassigned. Trigger point: First step of the segment
Item Snapshot Any point in the segment where the system takes a "snapshot" of the item and captures the details surrounding it. Can be used to capture the 'current state' of an item. Trigger point: Any node, transition, or action
Item Activity Occurs when an action is performed by a user (e.g., driver clicks on 'Deliver' button). Trigger point: Any action

📘

Before you proceed...

Please note that legacy webhooks require Bridge configuration and only supports 3 types of events. Before you proceed, consider using the latest webhooks instead. It is easy to set up and provides a complete set of events that you can subscribe to.

There are 4 steps to setting up legacy webhooks:

  1. Prepare your Endpoint
  2. Configure the Event
  3. Configure the Trigger
  4. Test Your Webhook

1. Prepare your Endpoint

Create a webhook endpoint URL on your server for receiving events. If you don’t have an existing server to test with, there are multiple free and paid tools online to set up a test webhook endpoint.

2. Configure the Event

In this step, you will create the events that trigger the webhook activity (e.g., when a delivery is completed, etc.)

To configure an event:

  1. Log in to your enterprise portal (e.g., example.zyllem.com). Don't have an account? Please contact your enterprise admin.
  2. Go to Settings > Events.
  3. Click on *Custom Events tab.
2260
  1. Click Add Custom Event.
3558
  1. Fill in the form (*required):
FieldDescription
Name*Name of event.
DescriptionDescription of the event.
Event Type*Select the event type. Learn more about the event types.
  1. Click Save.
  2. The event details will be displayed. Click + Add and select Webhook.
4218
  1. The webhook form will be displayed. Fill in the form (*required)
FieldDescription
Name of Notification*The name of the webhook activity
Notification DescriptionDescription of webhook activity
Webhook URL*Enter the endpoint you created in Step 1
HeadersIf your endpoint requires authentication (e.g., username, password), click Add row to add the key and value.
URL ParametersIf your endpoint requires other parameters, click Add row to add the key and value.
  1. Click Save.
  2. On the same page, test your endpoint locally by clicking on Test.
4142

Below is a sample response of a successful test:

{
  "id": "192a335c0000000000000000",
  "reference": "XKCD399",
  "trackingId": "1234-5678-abcd",
  "customProperties": [
    {
      "type": "ID",
      "name": "Custom Id",
      "codeName": "CUSTOM_ID",
      "value": "xyz-321-873n3"
    }
  ],
  "eta": {
    "from": "2019-03-25T18:04:54.87+08:00",
    "to": "2019-03-25T20:04:54.87+08:00"
  },
  "target": {
    "id": "192a335c0000000000000000",
    "externalId": "ctc-1234-b42",
    "company": "Zyllem pte ltd",
    "name": "John Smith",
    "phone": "+655555555",
    "email": "[email protected]",
   .....

3. Configure the Trigger

Once you have created the events, you need to configure the triggers that will fire the said events. This is done through the Bridge.

To add a webhook trigger:

  1. Open your Bridge. Or see the step-by-step guide for adding Triggers.
  2. Go to the point in the Bridge where you wish to add the trigger and click + Add Trigger.
4162
  1. Trigger Type, select Fire Event and click Next.
  2. Fill in the form (*required)
FieldDescription
Name*Name of trigger
DescriptionDescription of event
Event*Select the event you have created in Step 2. Don't see the event? Make sure you are at the right trigger point.

For the Execution condition field, refer to the table below:

1001
  1. Click Save.
  2. Publish your Bridge by clicking on Meta Data tab and then Publish.

4. Test Your Webhook

Now that you have configured the webhook event and trigger, you can now test your webhook events by performing the actual event.

To test your webhook:

  1. Book an item (or contact your Enterprise admin to facilitate the booking).
  2. Using the Zyllem app or web portal, execute the steps that will trigger the webhook events you configured in the Bridge (Step 3).
  3. To view the response schema, see Legacy Webhooks Reference

What’s Next