Webhooks

Webhooks are a common way for applications to send information to other applications over the internet. They're often used for notifications, data collection, and other integration purposes. Use webhooks to create moments in Hotpot.

Every Hotpot team can create specific webhook endpoints to send moments by a unique generated token. Each supported integration (for example, Datadog and PagerDuty) is available at a URL like https://api.hotpot.works/moment/<your API key>/<integration>.

Create moment webhooks

To create a moment webhook in Hotpot:

1. Go to your team's Settings page > Webhooks.

2. On the Webhooks page, create a new webhook with a name and optional service.

3. Copy the endpoint to your clipboard from the Token column. This gives you a URL that looks like: https://api.hotpot.works/moment/845b74c7730f219cd8bb1f0e6e13b3796014efe11c9e030ccc32. That's your $WEBHOOK_URL.

tip

Be careful with these endpoints. Anybody with that URL can create moments or pages, which could be surprising and confusing.

4. Use curl to create a test moment with a POST request. The two required parameters are name and type.

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

The full parameters available are:

{
  "name": "The name of the moment, 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 uses the current time"
}

Define a source_url

For Hotpot to be truly helpful, it needs to understand the sources of moments. 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 looks 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.

Send Hotpot moments with Python

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

Using Python as an example, copy and paste this code 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 }

Manage webhooks

To manage a webhook in Hotpot, go to your team's Settings page > Webhooks.

Rotate moment webhooks

If something happens that compromises your webhook URLs, you'll want to update them. To make this less stressful, set a future expiration date for the webhook in question. The webhook stays active until the expiration date while you transition services to use the new endpoint.

We display the incoming events 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's 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 learn how to page people, see the Hotpot API reference.