Skip to main content

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, asynchronous events, and other integration purposes. In Hotpot, you can use webhooks to create moments from any source.

Every Hotpot team can create specific webhook endpoints to send moments with 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 endpoint​

To create a moment webhook endpoint in Hotpot:

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

  2. On the Webhooks page, create a new webhook with a label (name) and type.

    The type--Datadog, Linear, and so on--helps identify the source of the webhook notification. To create a non-specific endpoint, use the Custom type.

  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 }

View webhook moments​

View all received webhook notifications under [profile icon] > Integrations > Webhooks. You can expand the details of each, and even retry those that errored.

Each integration page lists applicable webhook notifications under [profile icon] > Integrations > [integration] > Events.

Events and errors

Each integration Events tab shows moments sent to Hotpot by the integration. Each event is flagged as either success or error. Here, an event labeled error means the event was received but there was a problem with it (such as being ill-formed or lacking content). Hotpot answered the theoretical phone, but nothing intelligible was relayed.

Each integration Errors tab shows problems Hotpot had in contacting the integration. These are commonly caused by misconfiguration (like an invalid API key). Hotpot tried to call your integration, but couldn't connect.

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.