Introducing Webhook Actions

We are happy to make public our webhook-based event subscription system, known as Webhook Actions. If you've wanted more control over your webhook events with Anvil, then Webhook Actions are what you've been waiting for.

In this post, I'm going to talk about Webhook Actions in a bit more detail so you can understand what they are, how they work, and when you might want to use them.

What are Webhook Actions?

Webhook Actions are Anvil's system for subscribing to specific (or all) supported events on specific (or all) supported objects in your Organization. These events will be delivered via Webhooks.

The idea is this: when an event you are interested in occurs on an object you are interested in, Anvil will let you know about it via Webhook.

Our traditional webhook system is great, but lacks some flexibility. However, with Webhook Actions you can be as specific as you like (e.g. a specific event type on a specific object), or extremely broad (e.g. all events on all objects), or somewhere in between (e.g. a specific event type on all objects).

Setting up a Webhook Action requires you to determine 3 pieces of information:

1. What action(s) are you interested in monitoring for?
2. What object(s) are you interested in monitoring for those actions?
3. Where would you like us to make the Webhook call when this occurs?

Once you have determined the purpose of your Webhook Action, you can create one via the createWebhookAction GraphQL mutation:

mutation CreateWebhookAction($organizationEid: String, $action: String!, $objectType: String!, $objectEid: String!, $url: String) {
  createWebhookAction(organizationEid: $organizationEid, action: $action, objectType: $objectType, objectEid: $objectEid, url: $url) {
    eid
  }
}

For example, if you want to monitor for weldComplete events on a specific Weld, you might use the following variables for the above mutation:

{
  "organizationEid": "<your Organization's EID here>",
  "action": "weldComplete",
  "objectType": "Weld",
  "objectEid": "<your weld EID here>",
  "url": "https://yoursite.com/webhooks/anvil"
}

Webhook Actions also support "wildcards" in the action, objectType, and objectEid arguments. For example, if you want to monitor for weldComplete events across all of your Organization's Welds, you might use the following variables for the above mutation:

{
  "organizationEid": "<your Organization's EID here>",
  "action": "weldComplete",
  "objectType": "Weld",
  "objectEid": "*", // This signifies "all objects of the specified type"
  "url": "https://yoursite.com/webhooks/anvil"
}

For more examples, please see the detailed Webhook Action docs.

How do Webhook Actions work?

Whenever an event (i.e. action) occurs on an object, Anvil needs to determine if there's anyone we should notify about it. Based on the event we will check our database of active Webhook Actions to see if any of them are satisfied by the event that occurred.

For example, let's say that a weldComplete event occurred on a Weld with EID abc, creating a WeldData with EID xyz. The table below shows a few example Webhook Actions and whether they would be triggered by this event:

Depending on how many Webhook Actions you've set up and how you have configured them, it's possible that 1 event may satisfy several of your Webhook Action rules. For all Webhook Actions that are triggered by the event that occurred, we will group and de-duplicate them by their Webhook URL. This way you will not receive multiple identical webhook calls for the same event to the same URL.

When should you use Webhook Actions?

So when might you want to use Webhook Actions? The simple answer is: anytime you want to know about events of interest to you on objects of interest to you. Here are some more specific real-life examples:

• You want to notify a team whenever a form is filled out or a signature is completed.
• You have some complex processing that you need to do on a payload outside of our system.
• You want to download and store a resulting document from a workflow completion.

The reasons you might want to use Webhook Actions are pretty limitless, but they should be flexible and powerful enough for whatever your needs are. It's worth noting that Webhook Actions are the system that supports Anvil's Zapier integration - you may want to check that out before building something from scratch.

Conclusion

As an API-first company, we believe that Webhook Actions are going to be an important piece of the integration puzzle. While we've been leveraging Webhook Actions internally for some time (our Zapier integration is based on it), we are excited to make this capability public, and expose the power and flexibility of them to our customers. We'll also be adding more event types to the system over time. If there's something your organization needs feel free to reach out to us at support@useanvil.com.

Happy coding!