Using Webhooks

Use webhooks to be notified about events that happen within your Keygen account. If you need help after reading this, can reach out to us anytime at [email protected].

This tutorial is written in JavaScript, but you can follow along in any other language that you're comfortable in. Throughout this tutorial, you will see placeholders e.g. {ACCOUNT} within the code examples that will need to be replaced with your account's slug (or ID), or other resource information.

Before getting started, you will need to log into your Dashboard and generate a product token, which will be used to authenticate with Keygen's servers while accepting webhook events.

Your admin and product tokens carry many privileges and should always be kept secret. Do not share your secret API tokens in publicly accessible areas such GitHub, embed them in client-facing code e.g. inside of your product, and so forth. Learn more.

Webhook terminology

  1. Webhook events are certain events that happen within the context of your Keygen account, such as a user being created, a successful license validation, or your account being updated.
  2. Webhook endpoints are resources defined within your account to which Keygen sends event data to. A single webhook event may be sent to many webhook endpoints.
  3. Webhooks refers to the overall concept of sending webhook event data to an account's webhook endpoints.

About webhooks

Certain events that happen within Keygen's systems may not be immediately available when making an API request e.g., when a license expires. A naive solution for checking if a license has expired would be to poll Keygen's API every n minutes so that you can act upon that expiration at the time it occurs, e.g. to send an email to the license owner, or to update your own database records. This obviously wouldn't scale to hundreds or even thousands of licenses, causing a strain on both your systems as well as Keygen's systems with the amount of requests polling would require.

Webhooks solve this problem by letting you register a Webhook Endpoint URL that Keygen will notify anytime an event happens within the context of your Keygen account. When an event occurs e.g., when a new license is created by a user, Keygen creates a Webhook Event resource. This resource contains all the relevant information about what just happened at the time it happened, including the type of event and a snapshot of the data associated with that event.

Keygen then sends the Webhook Event resource to any Webhook Endpoints defined within your account via an HTTP POST request so that you can immediately act upon the event, allowing the potential for business automation. You can find a full list of webhook event types in the API docs.

When to use webhooks

The result of most Keygen requests (e.g., creating users or licenses) are reported synchronously to your code and don’t require webhooks for further action. However, depending on your business requirements, you may want to perform additional actions behind-the-scenes, e.g. after a user is created, you may want to also create a new Stripe customer, storing the stripeAccountId in the user's metadata attribute.

Automating communication between Keygen and your payment provider (e.g. Stripe) is the most common use-case for using webhooks, allowing you to respond to events on both sides. For example, when a license is created by one of your users within Keygen, you can charge their Stripe customer profile for that new license; or when a payment fails within Stripe, you can suspend their license within Keygen until the payment is successfully processed.

You might also use webhooks to:

  • Email a license key to a customer after a successful purchase
  • Update or create new records in your own database when a specific event occurs (when for example, you manage your users within your own database instead of within Keygen)
  • Email a user when a license expires (or better yet, before it expires!)
  • Automatically renew licenses before expiration using additional information from your payment provider (e.g. you may check if their subscription is still active before renewing)
  • Create an audit trail for events of importance for each user or license

Server-side integration

If you're using Keygen server-side, some of the above mentioned steps could potentially be done within a single transaction, but you may not want to introduce additional network latency to your user creation process via performing requests to Keygen as well as to your payment provider. Instead, you could listen for the user.created webhook event that Keygen will send and handle things with your payment provider asynchronously.

Client-side integration

If you're using Keygen client-side (i.e. allowing resource creation directly within your product), handling webhook events might be a must-have, seeing as you may not be able to also create and manage resources with your payment provider client-side, as you would be exposing your secret keys within your code. Instead, you can perform license and machine creation requests client-side while authenticated as the currently logged in user and listen for the corresponding webhook events to act accordingly e.g., charging them for new licenses, crediting them for deleted licenses or machines, etc.

Configuring a webhook endpoint

Webhooks can be configured within the webhook endpoints resource section of your account dashboard. Clicking New Endpoint will reveal a form to add a new URL for receiving webhooks.

You can enter any URL you'd like to have events sent to, but this should be a dedicated route or page on your server, coded per the instructions below. For security reasons, the webhook URL must use the HTTPS protocol.

Receiving webhook events

Creating a webhook handler on your server is no different from creating any other route or page on your website. With PHP, you might create a new .php file on your server; with Node and a framework like Express, you would add a new route with the desired endpoint URL.

Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, though if security is a concern, or if it's important to confirm that Keygen sent the webhook, you should use ONLY the event ID sent within the webhook to then retrieve the remaining details from Keygen. If the event doesn't exist, then it wasn't from us. The example below will be taking such a precaution.

When delivering webhook events to your endpoint, an event is considered failed if the endpoint responds with a non-2xx status code. It will automatically be retried with an exponential backoff. We will perform 25 retries over approximately 21 days or until your server responds with a 2xx status.

Example webhook handler using Node and Express

const fetch = require("node-fetch")
const express = require("express")
const app = express()

app.post("/my/webhook/url", async (req, res) => {
  const { data: { id } } = JSON.parse(req.body)

  // Fetch the webhook to validate it and get its most up-to-date state
  const event = await fetch(`https://api.keygen.sh/v1/accounts/{ACCOUNT}/webhook-events/${id}`, {
    method: "GET",
    headers: {
      "Content-Type": "application/vnd.api+json",
      "Accept": "application/vnd.api+json",
      "Authorization": "Bearer {PRODUCT_TOKEN}"
    }
  })

  const { data, errors } = await event.json()
  if (errors) {
    return // Webhook event does not exist
  }

  switch (data.attributes.event) {
    case "user.created":
      const user = JSON.parse(data.attributes.payload)

      // … do something when a user is created e.g. create a Stripe customer

      break
    case "license.created":
      const license = JSON.parse(data.attributes.payload)

      // … do something when a license is created e.g. charge a user

      break
  }

  // Let Keygen know the event was received successfully
  res.sendStatus(200)
})
Tip: A great way to test your webhook integration locally is to use ngrok, which allows you to create secure tunnels to localhost, HTTPS and all. Assuming you're running on port 8080, you can use the command: ngrok http -host-header=localhost 8080.

Next steps

Congrats! You've learned what webhooks are, when and how to use them, and how to receive events with your own server. If you have any questions about what you've learned today, be sure to reach out!