Events Data Model

Signals Events are stored in FireHydrant when a webhook is sent to FireHydrant that matches the correct data model. This guide will help you understand the data model that FireHydrant uses to define Events.

What makes a valid Signal Event object?

Signal Event object is a dictionary hashmap returned by transposer function that looks like the following:

{
  "summary": "CPU usage too high",
  "body": "VM CPU utilization is over 90%",
  "status": "OPEN",
  "idempotency_key": "18913k2b63ifs",
  "tags": [
    "name:myService",
    "region:us-west2"
  ],
  "annotations": {
    "acme-inc/team": "sre"
  },
  "level": "ERROR",
  "images": [
    {
      "src": "https://example.com/pic.png",
      "alt": "Snapshot from [P2] [Triggered] [TEST] Signals Test Monitor"
    }
  ],
  "links": [
    {
      "href": "https://datadoghq.com/event/event?id=238472398472582",
      "text": "Datadog Monitor"
    }
  ]
}

Data Model

Field NameTypeExample
summarytextCPU Utilization Spiking
bodytextThe production server is experiencing greater than 99% utilizations of compute.
statusenumEither OPEN (0) or CLOSED (1)
levelenumAny of:

- INFO (0)
- WARN (1)
- ERROR (2)
- FATAL (3)
annotationsobject{ “randomNumber”: 1234 }
imagesarray[ { "src": "https://site.com/images/123.png', "alt": "A simple, sample image" } ]
linksarray[ { "href": "https://site.com/monitors/123', "text": "Monitoring Source" } ]
tagsarray["tag1", "service:your-service-slug", "environment:production"]
idempotency_keytextA unique identifier used to group/deduplicate open alerts

Special Annotations

Special annotations are parameters that FireHydrant uses in Annotations for specific functions. These annotations are contained within the annotations field of the data model.

AnnotationAccepted ValuesDescription
signals.firehydrant.com/notification-priorityHIGH, MEDIUM, LOWThis annotation value is used by FireHydrant to set the alert's priority. The alert priority impacts how a user will be paged according to their personal notification preferences. If this annotation is not specified, then the alert defaults to HIGH.

To learn more, visit Notification Preferences.

Private Annotations

Private annotations are values FireHydrant will set internally based on various things. Do not set these values directly in the payload body, as they are sanitized upon ingestion before FireHydrant sets the values.

Private AnnotationDescription
private.signals.firehydrant.com/team-idThe UUID for the team being targeted. See Bypassing Rules in Alert Rules documentation on how to directly target teams.
private.signals.firehydrant.com/viaDenotes how the alert was sent. Possible values are:

- manually-paged - When alert is sent via web UI or from Slack's /fh page
private.signals.firehydrant.com/actor-idID of the actor who sent the page. If via chat app, it will be the user's ID in the chat app. If via web UI, it will be the user's UUID in FireHydrant
private.signals.firehydrant.com/actor-nameName of the actor (usually a user) who triggered the page.
private.signals.firehydrant.com/actor-sourceThe source of the actor who created the page. Possible values are:

- firehydrant_user - For any alerts created from web UI or chat apps
- api_key - For any alerts created via an API call
- integration - For any alerts created via an integration or Event source

Understanding the Idempotency Key

The idempotency_key is FireHydrant's way of identifying incoming events that need to be grouped together. For instance, if your monitoring tool sends two webhooks to FireHydrant with a matching idempotency_key, Signals will not create a new alert if an alert is already Open. If an alert from an event with that idempotency_key has been resolved or dismissed, Signals will create a new one.

Another use of the idempotency_key grouping is to auto-resolve flappy alerts. If your monitoring tool sends an OPEN and then CLOSED event to FireHydrant, the system will auto-resolve any alerts that were generated from the original event.

Tags and the Service Catalog

Using the service-tagging convention, you can automatically associate any Service Catalog component with your alerts and the incidents that get opened from those alerts.

To reference a service, use the service: prefix combined with the slug of your service in FireHydrant. These slugs can be found in your Service Catalog on each respective component's page in the Details section.

Where to find the slug on a component's details page

Where to find the slug on a component's details page

For example, let's take a service called API Gateway with a slug of api-gateway. It is in the Production environment (slug production) that has associated functionality called Public API with a slug of public-api.

The tags to automatically pull these components in would be: service:api-gateway, environment:production, and functionality:public-api. When you include a catalog component in your payload, any incidents that are opened from Alerts created by that payload will automatically mark those catalog components as impacted when the incident is opened. Below is the example payload:

{
  "summary": "CPU Utilization Spiking",
  "body": "The production server is experiencing greater than 99% utilizations of compute.",
  "level": "ERROR",
  "status": "OPEN",
  "idempotency_key": "ad98rb3b2b",
	"images": [
    {
      "src": "https://site.com/images/123.png",
      "alt": "A simple, sample image"
    }
  ],
  "links": [
    {
      "href": "https://site.com/monitors/123",
      "text": "Monitoring Source"
    }
  ],
  "annotations": {
		"policy": "escalatable"
  },
  "tags": ["service:api-gateway", "environment:production", "functionality:public-api", "random-tag"],
}

Return Values

When Events are sent to any of FireHydrant's Event Sources endpoints, there are some basic responses you can watch for:

Response CodeResponse BodyDescription
202 Accepted{ "success": true }General response when an Event Source ingestion is successful
400 Bad Request{ "errors": [ "STRING" ] }Array of error messages returned when an Event webhook's payload was invalid
429 Too Many Requests-Response when you have exceed the rate limit for ingesting events