Introducing ZeroTier Webhooks
We have a special treat for all of the network administrators out there for Halloween this year: Webhooks!
Now our paid customers can receive notifications from ZeroTier Central in the form of a webhook for many actions performed on our UI and/or API so you can log or react to things happening in your ZeroTier networks. Actions that will call out to webhooks include:
- A new machine joins a network
- An administrator authorizes or deauthorizes a network member
- An administrator changes the network configuration
- An administrator changes a member configuration
- An administrator creates or deletes a network
- An administrator deletes a member
- A new user is invited to, removed from, or accepts/rejects an invite to join your organization.
- A user performs an SSO login to your network
This new feature requires some initial work on your end to set up an endpoint to receive hooks from us. Read on for more details.
Configuring Webhooks
There’s a new spot for paid accounts on the account page to configure webhooks:
The Endpoint URL field is the URL to your hook receiver where we will send the requests. This URL must be accessible from the internet and should preferably be secured with https. The description is optional. Event Types lets you select which event(s) you want to receive callbacks for. You can also configure multiple webhook receivers, each with their own list of events to receive.
Standing Up a Webhook Receiver
If you just want to test things out and see how they work, you can test things with Zapier. For example, if you want to receive an email every time a new member tries to join your network you can configure the “Webhooks by Zapier” action to receive the webhook:
Make sure you select “Catch Raw Hook” as the event so you have access to the POST body in the next step of the workflow
Next add a “Send Outbound Email” step with your email address and attach the Raw Body output of the previous step to the email body:
Finally, make sure to grab the webhook URL that Zapier generates for you. On your account page on ZeroTier Central, create a new webhook and paste that for your hook URL and select “Network Join” as the event type. Save and publish your webhook configuration and Zapier workflow, and you’ll now receive an email every time a new member tries to join your networks!
Something A Little More Advanced
Zapier is nice for getting something going quickly, but you may already have existing systems you want to integrate with. We’re giving you some additional tools to do just that.
First is a Go library released under the Mozilla Public License Version 2.0 with structs for deserializing the hook into easier objects to work with, and also validating hook calls. We’ve also provided a simple example to get you started with the Go library.
There is also a TypeScript library for validating hooks.
Verifying Your Webhooks
Hooks are great and all, but since the endpoint calling out to is public, you need a way to make sure the calls to it are actually from us, and not some random person/bot on the internet trying to fool you. We’ve added Webhook Signing Secrets for just that purpose.
Once you generate a secret, all outgoing calls to your webhook endpoint will be signed with that secret in the X-ZTC-Signature HTTP header. Examples are given in the repositories for both the Go and TypeScript libraries, as well as on our documentation site.
You can have multiple signing secrets active at the same time to give you time to rotate your webhook receivers. When multiple secrets are present, the hook will be signed by all active secrets.
Let Us Know What You Think
Talk with us on Mastodon or The Site Formerly Known as Twitter and let us know what you think. Have any issues with the libraries? Open an issue and let us know. Feeling extra ambitious and want to add another language? Open a Pull Request! Make something really cool with this feature? Show us!
We hope these webhooks will give you a new tool in your tool box for managing your ZeroTier networks.
Happy Halloween from the ZeroTier team!