Webhooks

How to use webhooks to create moments in Hotpot.

Webhooks are a common way for applications to send information to other applications over the internet. They are often used for notifications, data collection, and other integration purposes. Hotpot uses webhooks to make it easy for your systems to send moments to us.

Each Hotpot team can create specific webhook endpoints to send moments by a unique generated token. Each integration that we support (e.g., Datadog, PagerDuty) is available at a URL like https://api.hotpot.works/moment/<token>/<integration>.

Creating and managing Moment webhooks

In Hotpot, go to your team's settings page, then to "Moment API" to create or manage the currently configured Moment API endpoints. Be careful with these endpoints, because anybody with that URL can create Moments and that could be surprising and confusing.

Leveraging webhooks for Hotpot requires a small amount of coding or using no-code tools like Zapier.

The quickest start: Creating a moment

On the Moment API page, create a New webhook with a name and optional service. The endpoint can be quickly copied to your clipboard in the "Token" column. That will give you a URL that looks like: https://api.hotpot.works/moment/845b74c7730f219cd8bb1f0e6e13b3796014efe11c9e030ccc32. This is your $WEBHOOK_URL

Use curl to create a fairly unhelpful moment with a POST request, with the only two required parameters name and type:

curl -X POST --json '{"name": "A thing happened", "type": "alert"}' $WEBHOOK_URL

The full parameters available are:

{
  "name": "This is the name of the moment, it must be a string up to 70 characters",
  "source": "Internal System Name",
  "source_url": "Reference URL of the moment's source",
  "description": "Detailed description, Markdown is supported",
  "type": "page|alert|near-miss|incident",
  "occurred_at": "ISO8601 formatted date when the moment happened, must be in the past, if not specified is the current time"
}

Sources and Source URL

For Hotpot to be truly helpful, it needs to understand what the sources of moments are. A source could be a person, tool, or specific integrations. If you have your own custom deploy tooling and want to submit a moment for a bad deploy, the payload would look like:

{
  "name": "Failed deploy with successful rollback",
  "source": "Deploybot",
  "source_url": "https://deploybot.corp.acme.com/deploys/725978",
  "description": "## Failed deployment!\n\nThe deploy failed but was able to be rolled back",
  "type": "near-miss",
  "occurred_at": "2023-04-01 12:31:26"
}

This tells Hotpot that Deploybot is a source of moments, connects into Deploybot, and helps the team pull in more details.

A brief Python example

Using Python as an example, you can copy and paste the code below into tools like Zapier, to send Hotpot moments.

import requests
webhook_url = "YOUR WEBHOOK URL"
payload = {
  "name": "Your Moment from Python",
}
r = requests.post(webhook_url, json=payload, verify=False)
output = { status: r.status_code }

Rotating Moment webhooks

If something happened that compromised your webhook URLs, we want to make it easy for you to update them. We know this process can be pretty stressful, and to help ease that you can set a future expiration date for the webhook in question and it will stay active until that point while you transition services to use the new Moment API endpoint.

We display the incoming events that were sent through that endpoint, which hopefully helps identify the sources that need updating.

Moments and Pages

Hotpot is the best way to set up, manage, and be on-call. There is a relationship between emergent disturbances (Pages) and other things that may require human attention (Moments). We're working to unify the workflows, but for now these are fully separate.

To see how to page people, read our API reference:

API Reference