Skip to main content

Receive Notifications

Receive Notifications

In this guide, we will set up a webhook to receive notifications from the Hyperion API.

Overview​

Webhooks provide a way to receive real-time notifications when activities occur in the Hyperion platform. Instead of polling the API for changes, you can configure a webhook endpoint that Hyperion will call whenever relevant events happen.

Webhooks can notify you about activities such as event creation, monitorable updates, a member added to your partner account, or monitorable incident actions from ADT operators (monitorable-incident:create and monitorable-incident:action:create). See Monitorable Incidents for the mapped action names.

Getting Started​

Before creating a webhook, you need:

  1. An application with the webhook:write scope. If you haven't created an application yet, see the Create Application guide to get started.
  2. A publicly accessible HTTPS endpoint that can receive webhook notifications.

Once you have your application credentials, use the Set Access Token button in the navbar to configure your access token for making API requests.

Create a Webhook​

To create a webhook, send a POST request to the /webhooks endpoint with your webhook configuration:

Request body

Webhook endpoint URL

application:create
application:update
application:delete
event:create
event:update
member:create
member:update
member:delete
member-invitation:create
member-invitation:accept
member-invitation:resend
member-invitation:delete
monitorable:create
monitorable:update
monitorable-incident:create
monitorable-incident:action:create
monitorable-requirement:update
monitorable-system-status:create
monitorable-system-status:update
monitorable-system-status:delete
webhook:create
webhook:update
webhook:delete

List of activity types to subscribe to

Whether the webhook is enabled

cURL command

cURLPOST
curl -X POST "/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
  "activityTypes": [
    "event:create",
    "monitorable:create"
  ],
  "enabled": true,
  "url": "https://example.com/webhooks/hyperion"
}'

💡 Set your access token in the navbar to auto-fill the Authorization header

Response​

Upon successful creation, you'll receive a response containing the webhook details:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "partnerId": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://example.com/webhooks/hyperion",
  "activityTypes": ["event:create", "monitorable:create"],
  "enabled": true,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Webhook Payload​

When an event occurs that matches your webhook's activityTypes, Hyperion will send a POST request to your webhook URL with a JSON payload containing the activity details. The data field contains an object snapshot of the entity at the time of the activity:

Webhook activity

Example payload

event:create

JSON
1{
2  "id": "550e8400-e29b-41d4-a716-446655440000",
3  "partnerId": "550e8400-e29b-41d4-a716-446655440001",
4  "entityId": "550e8400-e29b-41d4-a716-446655440002",
5  "entityType": "EVENT",
6  "activityType": "event:create",
7  "scope": "event:read",
8  "data": {
9    "id": "550e8400-e29b-41d4-a716-446655440002",
10    "externalId": "ext-event-12345",
11    "partnerId": "550e8400-e29b-41d4-a716-446655440001",
12    "monitorableId": "550e8400-e29b-41d4-a716-446655440003",
13    "systemStatus": "ACTIVE",
14    "createdAt": "2024-01-15T10:30:00Z",
15    "updatedAt": "2024-01-20T14:45:00Z"
16  },
17  "createdAt": "2024-01-15T10:30:00Z"
18}

Set an access token using the Set access token button in the navbar to send test webhooks.

Verifying Webhook Signatures​

Each webhook request includes three signature headers following RFC 9421 (HTTP Message Signatures):

  • Signature-Input: Contains the signing key ID and creation timestamp, e.g., sig=("@content");created=1618884473;keyid="<key-id>"
  • Signature: Contains the base64-encoded signature wrapped in colons, e.g., sig=:<base64-signature>:
  • Signature-Agent: The fully qualified JWKS URL for fetching verification keys

Parse the label and keyid from the Signature-Input header, extract the label and signature from the Signature header, confirm the labels match, fetch the matching public key from the JWKS URL in the Signature-Agent header, and verify the signature against the raw request body using the algorithm specified in the key's alg field. The label (e.g., sig) must match between both headers -- always parse it dynamically.

For a detailed verification walkthrough with code examples, see the Webhooks concept page.

Conclusion​

You've successfully created a webhook to receive real-time notifications from the Hyperion platform. Your webhook endpoint will now be called whenever events matching your configured notification types occur.

Learn More​

  • Webhooks - Deep dive into webhook configuration and payloads
  • Events - Activities that trigger webhook notifications
  • Monitorable Incidents - Learn how to subscribe to monitorable incidents and operator actions
  • Monitorables - Entities that generate events

API Reference​