sorted.REACT logo

Managing Webhooks

SortedREACT uses webhooks to notify you of shipment events. This page explains how REACT webhooks work, how you can control them using Shipment State Groups, and how to set webhooks and Shipment State Groups up in the UI.

On This Page


What is a Webhook?

A webhook is an automated message sent by an app whenever a particular event occurs. The principle is fairly simple: you tell the app where to send the data (i.e. the URL it should send to) and when to send (i.e. the circumstances in which you want to receive data). Whenever those circumstances occur, the webhook sends its payload to the location you specified. You can then use that data in whatever way you need.

The key is that the webhook sends data to you proactively - you don’t need to make a request like you would with a “regular” API. This enables you to build efficient services that don’t need to continually poll an app for changes in order to stay up to date.

Webhooks in REACT

In REACT, webhooks are used a means of keeping you up to date with registered shipments. They are triggered by changes in shipment state. When a shipment enters a pre-selected state, REACT sends the current details of the shipment and the event that caused it to change state to a pre-configured location.

These timely updates mean that you can automate processes such as customer communications and carrier escalations. For example, you might set up a webhook that sends data whenever a shipment enters a state of Delayed. You could then feed the data from that webhook into your SMS gateway so that your customers are immediately alerted by text when delays occur.

Webhook Payload

When a shipment state change triggers a webhook, the webhook sends the Shipment Events resource for the event that caused that shipment state change in its payload body. The data sent has the same structure as the response from the Get Shipment Events API.

More Information:

For full reference details of the Shipment Events resource, click here.

The Shipment Events resource has two main parts:

  • shipment - This object contains a summary of the data REACT holds on the shipment in question, including reference numbers, carrier information and expected dates.
  • events - This object contains details of the event that triggered the relevant shipment state change, including timestamps and a list of the properties that were changed as a result of the event.

It’s worth paying particular attention to the property_summary array within the events object. This array lists any changes to the shipment.shipment_state.state, shipment.delivered_date, shipment.promised_date, and shipment.shipped_date properties that occurred as a result of the event that triggered the webhook, including what each property was changed to and what it was set to previously.

The richness of the data returned by the Shipment Events resource will depend to some extent on the data that was provided when the shipment in question was registered. If a webhook returns a shipment that was registered with just a carrier tracking reference, then the resource will only contain event details and that carrier tracking reference.

However, if a webhook returns a shipment that was registered with additional details (such as custom references and promised dates) then these details will be sent as part of the webhook’s payload, enabling you to build services that use this information without having to look it up elsewhere.

Webhooks and Shipment State Groups

Each REACT webhook must be associated with at least one Shipment State Group. A Shipment State Group is a set of shipment conditions that is used as a webhook trigger. When a tracking event causes a shipment to change state so that it meets the criteria set out for a particular shipment state group, any webhooks that are associated with that group will send their data.

More Information:

All REACT shipments have a current shipment state, which is updated as shipment events occur.

For a full list of REACT shipment states, see the Shipment States page.

Shipment states can be grouped in whatever way you choose. For example, you could set up a group containing states that require escalation to the carrier, such as Lost, Damaged, and Missing. You could also set up a group containing states that you would want to send delivery updates to your customers on, such as Out For Delivery, Collection Reminder, and Delivery Attempted. The Example Configuration section gives further examples of potential Shipment State Groups.

In REACT, each Shipment State Group can trigger multiple webhooks, and each webhook can be triggered by multiple groups. This many-to-many relationship enables you to create flexible configurations that don’t tie your business processes into your webhook configurations.

Managing Your Shipment State Groups

Shipment State Groups are managed in the REACT UI via the Settings > Shipment State Groups page. This page enables you to set up new groups and edit or remove existing ones. It displays a card for each shipment state group that you set up.

You’ll need to set up your groups before configuring webhooks, as selecting Shipment State Groups is part of the webhook configuration process.

Creating New Shipment State Groups

  1. Log into the REACT UI and select Settings > Shipment State Groups to display the Shipment State Groups page.

    create-SSG

  2. Click the Create New tile to begin creating a new group. The Name Your Shipment State Group tile is displayed.

    create-SSG2

    Tip:

    Give your group a name that is related to the business process you want to drive with the group rather than the communication method you want to use with the customer. For example, “Contact Required” would be a better choice of group name than “SMS”.

  3. Give your group a name and click Next to display a list of available shipment states.

    create-SSG3

  4. Select the shipment states you want to add to the group. If required, you can filter the list and search for individual shipping states using the controls at the top of the tile.

    When you’ve selected everything you need, click View Selected. A list of the states you selected is displayed.

    create-SSG4

  5. You can deselect states from this tile if you need to. When you’re happy with the states in the group, click Next to display a list of shipment types.

    create-SSG5

  6. Select the shipment types you want to include and then click Next to display the Add shipment tags tile.

    create-SSG6

  7. If required, add shipment tags by entering a tag name and clicking the plus button. If you select tags then only shipments that are tagged with at least one of those tags can trigger webhooks via your group.

    Note:

    Tags can be added to shipments via the Register Shipments and Update Shipments endpoints. For more information on adding tags to shipments, see the Registering Extra Shipment Information section of the Registering Shipments page, and the Updating Shipments page.

    When you have added any tags you need, click Create Group to finish creating the group. Your new group appears as a tile on the Shipment State Groups page.

Editing Existing Shipment State Groups

To edit an existing Shipment State Group, click the Edit button on that group’s tile. The process of editing an existing group is the same as that used to set up a new group.

edit-SSG

To delete an existing Shipment State Group, click the Delete button on that group’s tile and click Confirm on the pop-up confirmation dialog. You cannot delete a shipment state group if it is currently being used by one or more webhooks.

delete-SSG

Managing Your Webhooks

Webhooks are managed in the REACT UI via the Settings > Webhooks page. This page enables you to set up new webhooks and edit or remove existing ones. It displays a card for each webhook that you set up.

Creating New Webhooks

  1. Log into the REACT UI and select Settings > Webhooks to display the Create Webhooks page.

    create-WH

  2. Click the Create New Webhook tile to begin creating a new webhook. The Name Your Webhook tile is displayed.

    create-WH2

  3. Give your webhook a name and click Next to select Shipment State Groups.

    create-WH3

    Tip:

    If you haven’t set the required Shipment State Groups up yet, click the Create Shipment State Group link to jump to the group creation process. You will lose any unsaved configuration for your webhook.

  4. Select the Shipment State Group(s) that you want to trigger your webhook and click Next to select shipping state label languages.

    create-WH4

    In order to receive shipment state labels in a language other than English (Great Britain), you’ll need to have configured custom shipping state labels in that language via the Settings > Shipment State Labels page.

  5. Select the language you want to receive shipment state labels in. The default is English (Great Britain). Click Next to set up authentication.

    create-WH5

  6. Select the authentication method for the service you want the webhook to send its data to. REACT supports outbound authentication via API Key, Basic authentication and JSON Web Token (JWT):

    • API Key - Select the API Key tab and enter the Request header and API key value that the webhook should authenticate with. The webhook will send this key-value pair every time it sends data.

    create-W6b

    • Basic - Select the Basic authentication tab and enter the Username and Password that the webhook should use. The webhook will authenticate with these details every time it sends data.

    create-W6a

    • JWT - To set up JWT webhook authentication, you’ll need to be running a service that can create JWT tokens and pass them back to REACT. When you configure JWT authentication in REACT, you specify the details of that service and tell REACT where in the webhook data it should place the token it receives.

      The setup process is as follows:

      1. Select the JWT tab to display the JWT configuration fields.

        create-W6ca

      2. Enter the URL of the service REACT should make the JWT request to.

      3. Enter any JSON that REACT will need to include in the body of the request into the JSON Request Body field.

        For example, if your JWT service requires callers to supply a username and password in the body of the request, you could enter the following into this field:

        {
         "username": "EXAMPLE_USERNAME",
         "password": "EXAMPLE_PASSWORD"
        }

      Example JWT JSON request body.

      1. Enter the HTTP Method that REACT should use when requesting the token.

        create-W6cb

      2. Enter the header that the webhook should send the resulting JWT token in into the Request Header field.

      3. Enter the value mask that REACT should use when sending the resulting token into the Value Mask Format field. The token itself should be represented as $JWT$.

        Note:

        The Request Header and Value Mask Format fields enable you to specify exactly how REACT should use the token it receives from your authentication service. When a JWT-authenticated webhook sends data it places the token inside the header key specified. The corresponding value for this header key is the contents of the Value Mask Format field, where $JWT$ represents the token itself.

        For example, if you wanted REACT to send the token in a header named Authentication, with a corresponding key of Bearer (token), you would enter:

        Request Header: Authentication

        Value Mask: Bearer $JWT$

      4. Enter any headers that REACT should use when requesting the token by entering a Key and Value and clicking the Add button.

      5. Click Next to finish setting up authentication.

        Note:

        Your JWT service should be configured to return JWT tokens in the following format: {"access_token": "[jwt-here]"}. REACT cannot accept tokens in alternative formats.

  7. When you have entered your authentication details, click Next to set up headers.

    create-WH7

  8. If required, enter any headers you want the webhook to include in the data it sends to you by entering their Key and Value and clicking Add. Adding headers is optional. You can add multiple headers if you need to.

    When you’ve added any headers you need, click Next to set up your webhook URL.

    create-WH8

  9. Enter the Request URL you want the webhook to send its payload to and select whether you want it to use a POST or PUT HTTP method when sending data to your service.

    If you need to, click Send Test Webhook to test your webhook configuration. The panel on the card shows what the payload will look like.

    Note:

    You should enter your Request URL details carefully, as REACT doesn’t attempt to re-send data in cases where a webhook could not be received.

  10. When you’re happy with your setup, click Create to create the webhook. Your new webhook appears as a tile on the Webhooks page.

Editing Existing Webhooks

To edit an existing webhook, click the Edit button on the webhook’s tile. The process of editing an existing webhook is the same as that used to set up a new one.

edit-WH

To deactivate and reactivate a webhook, click the Active / Inactive toggle on the webhook’s tile. Deactivating a webhook means that it will not send data even if a shipment assumes one of the states in an associated Shipment State Group.

active-WH

To delete an existing webhook, click the Delete button on the webhook’s tile and click Confirm on the pop-up confirmation dialog.

delete-WH

Example Configuration

This section gives a simplified example of how webhooks and Shipment State Groups can be linked. Suppose you want to set up the following business processes:

  • If a shipment is In Transit, Delivered, or has a Collection Reminder available, send an SMS update to the customer.
    You could put these states in a Shipment State Group called Updates.
  • If a shipment has a Final Collection Reminder available, or is in a state of Action Required, send SMS and email updates to the customer.
    You could put these states in a Shipment State Group called Action Required.
  • If a shipment has a Proof of Delivery available, send an email to the customer.
    You could put this state in a Shipment State Group called For Reference.
  • If a shipment is Delayed, send an SMS update to the customer and escalate to the carrier.
    You could put this state in a Shipment State Group called Escalate and Update.
  • If a shipment is Damaged or Destroyed, escalate to the carrier without initially sending an SMS to the customer.
    You could put these states in a Shipment State Group called Escalate.

You could then set the following webhooks up:

  • One that sends data to your SMS gateway to trigger text shipment state updates to your customers.
  • One that sends data to your Email gateway to trigger email shipment state updates to your customers.
  • One that sends data to your CRM, from where it is used to generate escalation cases with your carriers.

During the webhook setup process, you would link the webhooks to the Shipment State Groups as follows:

Example webhook and Shipment State Group configuration diagram.

Note that the Shipment State Groups are based around business processes, and the webhooks are based around the services you want REACT to communicate with. This means that if you want to, say, change the Updates group so that it sends out Whatsapp messages instead of SMS, you could use your existing group with a new webhook. Equally, if you wanted to use email updates with a new Shipment State Group, you could simply create the group and add it to the existing Email webhook.

However, this is only a suggested workflow. REACT enables you to combine Shipment State Groups and webhooks in whatever way you feel is best for your business.

Note:

If you use webhooks to set up automated customer communications, consider asking your carrier to disable any automated tracking updates they may send to customers. Otherwise, customers might receive duplicate communications.

Next Steps

Learn more about the REACT UI: