Here’s a common question: what’s the difference between APIs and webhooks? Well, webhooks can be thought of as user-defined HTTP callbacks that are triggered by specific events. Whereas API calls work on request-based output mechanisms, webhooks work on event-based output mechanisms.

And, even though webhooks are a subset of APIs, they’re sometimes (affectionately, we think…) referred to as reverse APIs. But what happens when they’re not secure? Or if they’re intercepted or manipulated in some way? What are the best ways to protect your webhooks?

These are the questions that ngrok, who have an API-first ingress-as-a-service offering, set out to answer when they put Webhooks.fyi live last year. The site made some waves on ProductHunt (it was ranked #5 Product of the Day in November 2022).

However, its launch was perhaps overshadowed by that substantial funding round — to the tune of $50 million — that ngrok closed at the end of last year. Nevertheless, Webhooks.fyi is well and truly rolling in 2023 and continues to grow. But what exactly does it aim to do?

In general, encouraging more standards around webhook design (and API design in general) represents a net positive for the community at large. We talked briefly to Keith Casey, Director of Product Marketing at ngrok, to explore the goals of Webhooks.fyi, and to see how it can help webhook creators.

What Is Webhooks.fyi?

Webhooks.fyi is a webhooks knowledge center maintained by ngrok.

Webhooks.fyi is exactly what it sounds like: a knowledge center for webhook best practices. Casey calls it a “side effect of our webhook verification efforts.” As of 2023, it catalogs many webhooks and identifies helpful best (and worst) practices.

Casey goes on to say that “most people start with ngrok to wire webhooks into their apps. Unfortunately, we also know that many people don’t verify those webhooks and have effectively created a backdoor into those apps.”

To improve webhook security practices, Webhooks.fyi breaks down various aspects of webhook security, like One Time Verification, HMAC, OAuth2, and mTLS. It also explains webhooks operations such as Resiliency, Forward Compatibility, Zero Downtime Rotation, and so on. All these areas are broken into simple terms with code snippets and examples.

One helpful section, for example, covers tips to make great documentation for webhooks. In addition to offering interesting comments about webhooks in particular – like the fact that 10% of webhooks investigated for the site missed critical information in their documentation – this stuff has plenty of applications that go way beyond webhooks.

Webhooks.fyi covers helpful security and operational best practices for developing webhooks.

The Goals of Webhooks.fyi

Casey has written elsewhere that “in building our in-product webhook verification, we explored over 100 different approaches to webhook verification, security, reliability, and upgradability and learned that products were all over the map.”

He clarifies to Nordic APIs that “we realized we had built a directory of methods, documentation, and examples, and had identified some best and worst practices. It only felt right to share our work to make it easier for the next team.”

In addition to extracting best practices, with a view to identifying de facto standards, the team published a directory of documentation and supplementary information about webhooks from a number of companies. The Webhook Directory currently contains listings from over 50 providers, including Airship, Bolt, Box, Contentful, Hubspot, Microsoft Teams, Slack, and many more.

Casey sums up the aim of the site as follows: to help companies and individuals “build and use webhooks better going forward.” And, putting his money where his mouth is, Casey spoke about the project in Webhooks: Lessons (Un)learned at THAT Conference in early 2023.

The Webhooks.fyi directory of webhooks lists popular webhooks from Airship, Bolt, Coinbase, Contentful, and many more.

How Did We Get Here?

Webhooks are generally relatively narrow in scope. They, ostensibly at least, don’t need the same level of documentation as APIs. And they’re often used internally rather than being exposed to third parties. Consequently, there’s never really been an open standard for webhooks in the same way that APIs have the OpenAPI Specification.

Webhooks.fyi is a huge step in the right direction when it comes to establishing standards for implementing webhooks. It can be thought of as a set of published best practices for folks who want to use them. As ngrok lays out on the site, there are all sorts of measures that can be taken to secure webhooks, ensure forward compatibility, and so on.

The aim here isn’t necessarily to ensure that every webhook looks and acts in exactly the same way, but that they all meet certain minimum requirements when it comes to security and operations. All of which will make webhooks a little bit safer, and a lot more useful.

As for the goals of the project moving forward? Casey lists two big ones, although they’ve been there since the beginning of the project:

1. Teach developers how to use webhooks more easily and securely.
2. Organize patterns and practices to help providers build better webhooks.

“Along the way,” he adds, “we’ve attracted the attention of people building shared signals and events patterns, so we hope there are places to work together and improve the overall ecosystem. We’ve had a couple major webhook providers working on their next revision contact us for advice and share early access to their docs. It was a pleasant surprise and hopefully just the first.”

What Does the Future of Webhooks Hold?

In 2021, Zendesk made the decision to ditch HTTP targets and focus entirely on webhooks, facilitating the passing of information to all sorts of third-party platforms and tools. Although there’s nothing novel about stating that we’re seeing lots of companies open up their data, it is worth noting that increased adoption of webhooks (like the many organizations moving towards API-first design) reflects this movement.

But there’s another layer at work here: an API says, “here’s that information you wanted”, whereas a webhook says, “heads up, this just changed!” Beyond the technical implications of this (fewer API calls are required), it speaks to an improved flow of communication between the two services. And, as any marriage counselor will tell you, better communication makes for a better relationship. In other words? Wider adoption of webhooks signals companies and products working together in a less transactional way than one based on APIs alone.

As Casey points out, “there’s still a huge gap around topics like testing, retries, error capture, recovery, circuit breaking, and more.” As the API economy continues to gather steam, we expect to see more and more conversations around those topics and webhooks as a whole.

If you’re interested in adding to the conversation, whether with your favorite webhooks or examples from your own company, you can always contribute to Webhooks.fyi. We’re sure they’d appreciate the input!