Webhooks

Webhooks are one of the ways through which web applications can communicate with each other. They allow us to send real-time data from one application to another whenever a specified event occurs.

To create a webhook, navigate to Setup > Database tab > Tools > Webhooks, and click the New button.

By default, your new webhook is configured with the most commonly used options and is ready to be saved.

New Webhook

The description of the options is provided below:

Endpoint: The portion that follows your-database-url/hooks/ is generated randomly by default and is unique for a database. However, you can provide a meaningful name.
Name: The name of a new table where webhook data will be stored.
Notes: Any text you want to associate with your webhook.
Sender: The first three options denote the data format the webhook expects to receive when no special processing is required. Other options are services that either require specific responses or need a shared secret to calculate the signature. If the service you are integrating with requires either, please contact us at support@teamdesk.net, and we will add it to the list.

You can find a detailed example of how to use webhooks for integration with HelloSign in the following blog post. It is also possible to use the GET method with webhooks. Check the details in this blog post.

Iterators in Webhooks

Iterators allow you to select repeating entries from JSON or XML payloads and create a record in a table for each selected entry.

Let’s take an integration with Xero accounting software as an example.

When something changes in Xero, it sends the event to your webhook, listing what was changed, the type of change, and the identifier of the changed resource. The typical JSON payload it sends looks like this:

{
  "events": [
    {
      "resourceUrl": "<https://api.xero.com/api.xro/2.0/Invoices/01234567-0123-4567-8901-012345678901>",
      "resourceId": "01234567-0123-4567-8901-012345678901",
      "eventDateUtc": "2021-01-01T00:00:00.000",
      "eventType": "UPDATE",
      "eventCategory": "INVOICE",
      "tenantId": "01234567-0123-4567-8901-012345678901",
      "tenantType": "ORGANISATION"
    }
  ],
  "firstEventSequence": 1,
  "lastEventSequence": 1,
  "entropy": "ABCDEFGHIJKLMNOPQRST"
}

In your webhook, you should normally have:

A column to store either the resource ID or URL
An assignment to that column, like this: Response("$.events[0].resourceUrl")
A change trigger that works when a record is created
And a Call URL action that gets the full resource information based on the stored resource ID/URL.

However, you might have noticed that the "events" field is an array (or list if you prefer). For the most part, you’ll have only one item in the list, but depending on the change rate or Xero’s load, it may package multiple events together. Xero is not unique in this; there are many other APIs that bundle events to reduce server load.

With multiple events packed together, you’ll get something like this:

{
  "events": [
    {
      "resourceUrl": "https://api.xero.com/api.xro/2.0/Invoices/01234567-0123-4567-8901-012345678901",
      "resourceId": "01234567-0123-4567-8901-012345678901",
      "eventDateUtc": "2021-01-01T00:00:00.000",
      "eventType": "UPDATE",
      "eventCategory": "INVOICE",
      "tenantId": "01234567-0123-4567-8901-012345678901",
      "tenantType": "ORGANISATION"
    }, 
    {
      "resourceUrl": "https://api.xero.com/api.xro/2.0/Invoices/98765432-3210-3210-3210-109876543210",
      "resourceId": "98765432-3210-3210-3210-109876543210",
      "eventDateUtc": "2021-01-01T00:00:01.000",
      "eventType": "UPDATE",
      "eventCategory": "INVOICE",
      "tenantId": "01234567-0123-4567-8901-012345678901",
      "tenantType": "ORGANISATION"
    }
  ],
  "firstEventSequence": 1,
  "lastEventSequence": 1,
  "entropy": "ABCDEFGHIJKLMNOPQRST"
}

Our webhooks use the "one request creates one record" model. So, if you are going to handle multiple events, you’ll have to duplicate the logic: another storage column, assignment, trigger, and action for each event. But the real problem is that you do not know how many items might be in the list — any number you plan to handle might not be enough.

But now we have iterators to help!

Iterators allow you to select repeating entries from JSON or XML payloads and create a record in a table for each selected entry.

In the case of Xero, first, you should declare that you are going to iterate over the "events" field. First, create a "Xero Events" table and set up all the logic described above (column, trigger, action) there.

Now, for the iterator setup. Check the incoming data and click on a value (the "resourceUrl" field) you are interested in:

Assignment Expressions

You’ll see two new boxes displayed for the content that might be iterated. Copy the values. Now, go back to the webhook setup. There’s also a new "Iterators" section:

Webhook Iterators

Create a new iterator and paste the expression from the top box there.

Xero Edit Iterator

Save and create a new assignment. The end result will look like this:

Xero Webhook Iterator

Voilà! We are now capable of handling any arbitrary number of events in the Xero webhook! We will process each event uniformly, and there’s no need to duplicate the logic.