Webhooks
Webhooks are one of ways web applications can communicate with each other. It allows to send real-time data from one application to another whenever a given event occurs.
To create a webhook, navigate to Setup >> Database tab >> Tools >> Webhooks, click New button.
By default your new webhook is configured to most commonly used options and is ready to save.
The description of the options is provided below:
|
Option |
Description |
|
Endpoint |
The piece that follows your-database-url/hooks/ is generated randomly by default and it is unique for a database, though you can provide some meaningful name. |
|
Name |
The name of a new table where webhook data will be stored. |
|
Notes |
Any text you want to attribute your webhook with. |
|
Sender |
The first three options denote the data format webhook expects to receive when no special processing is required. Other options are services that either require some special responses or need a shared secret to calculate the signature. If the service you are integrating with requires either please drop us a note at support@teamdesk.net and we will add it to the list. |
You can find the detailed example how to use webhooks for integration with HelloSign in the following blogpost.
Iterators allow you to select repeating entries from JSON or XML payload and create a record in some 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, type of change and identifier of the changed resource. 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 resource ID or URL
- An assignment to that column, like this: Response("$.events[0].resourceUrl")
- A change trigger that works when record is created
- And a Call URL action that gets full resource information based on stored resource ID/URL.
But you might have noticed “events” field is decorated as array (or list if you prefer). For the most part you’ll have the only item in the list, but depending on change rate or Xero load it may pack multiple events together. And Xero is not unique, there are many other APIs that pack events together to reduce server load.
With multiple events packed together you’ll get the sort of:
{
"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 “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 and assignment and trigger and action for each event. But real problem is that you do not know how many items might be in the list — any number you are going to handle might not be enough.
But now we have iterators to help!
Iterators allow you to select repeating entries from JSON or XML payload and create a record in some table for each selected entry.
In Xero case first you should declare you are going to iterate over the “events” fields. First, we’ll create “Xero Events” table and set up all the logic described above (column, trigger, action) there.
Now to iterator setup. Let’s check incoming data and click on an value (“resourceUrl” field) we are interested in:
You’ll see two new boxes we display for the content that might be iterated. Let’s copy the values. Now, let’s go back to webhook setup. There is also new Iterators section:
Let’s create a new iterator and paste the expression from the top box there.
Save and create a new assignment. The end result will look as:
Voilà! We are capable to handle any arbitrary number of the events in Xero webhook! We will process each event uniformly and there is no need to duplicate the logic.
Next: Third-Party Accounts