Skip to main content

​
Runbook Hooks

The recommended way to integrate Hoop with external systems — SIEMs, alerting pipelines, audit platforms — is through runbook hooks. Hook scripts live in your runbooks git repository and execute automatically when session events occur, with the full event payload available as an environment variable.
Runbook hooks require version 1.36.11+ and the Runbooks plugin configured with a git repository.

​
How It Works

Place hook scripts in a hoop-hooks/ directory in your runbooks repository. Hoop executes the matching script automatically when the corresponding event fires, injecting the event payload as HOOP_RUNBOOK_HOOK_PAYLOAD.
FileEventDescription
hoop-hooks/session-open.runbook.pySession openFires when a session starts. May fire more than once if the connection has reviews enabled.
hoop-hooks/session-close.runbook.pySession closeFires when a session ends.

​
Enabling Hooks

Set GIT_HOOK_CONFIG_TTL in your runbooks plugin configuration. This activates hook support and controls how long (in seconds) the configuration is cached between git fetches. See the Runbooks configuration guide for full setup instructions.
Use a higher TTL if your hook scripts change infrequently — this reduces the number of requests to your git server.

​
Event Payload

The HOOP_RUNBOOK_HOOK_PAYLOAD environment variable contains a JSON object with session context. The event_session_open or event_session_close attribute is populated depending on which event fired. 
{
  "id": "7b769f42-a8a2-45cb-b0a1-e2d039385365",
  "sid": "8c59a347-62bd-4db2-a456-2b25963dfebf",
  "command": ["python3"],
  "event_session_open": {
    "verb": "connect",
    "connection_name": "pg-readonly",
    "connection_type": "database",
    "connection_subtype": "postgres",
    "user_email": "user@domain.tld",
    "connection_reviewers": [],
    "input": "SELECT * FROM customers WHERE id = 1"
  },
  "event_session_close": {
    "exit_code": 0,
    "output": ""
  }
}

​
Forwarding Events to a SIEM

The example below shows a session-close hook that forwards the event payload to an external endpoint — a SIEM, a logging pipeline, or any HTTP receiver. 
# hoop-hooks/session-close.runbook.py
import json, os, subprocess

payload = os.getenv('HOOP_RUNBOOK_HOOK_PAYLOAD')
event   = json.loads(payload)

subprocess.run([
    'curl', '-s', '-X', 'POST', 'https://your-siem.example.com/events',
    '-H', 'Content-Type: application/json',
    '-H', 'Authorization: Bearer <your-token>',
    '-d', payload
], check=True)

print('Forwarded session {} to SIEM'.format(event['sid']))
For more on writing and configuring runbooks, see the Runbooks configuration guide.

​
Svix Integration

The Svix webhook integration is deprecated. Use Runbook Hooks instead.

​
Prerequisites

​
Configuring

Log in and create the webhooks plugin: 
hoop login
hoop admin create plugin webhooks
Then enable it for a specific connection: 
hoop admin create plugin webhooks --overwrite --connection bash-default

​
Dashboard

Open the Svix dashboard to configure endpoints and subscriptions: 
hoop admin webhooks-dashboard
The dashboard is only available with Svix SaaS and can only be opened by administrators.
To view activity, interact with any connection. The Message Logs link shows all connection events.

​
Adding Endpoints

Click Endpoints to route messages to your SIEM.
Adding endpoints to a self-hosted Svix instance requires the Svix CLI or API.
Use Svix Play to test endpoints before wiring up production systems.

​
Event Types

Refer to the Event Catalog link in the dashboard for event definitions.

​
Consuming Webhooks

Refer to the Svix documentation for guidelines on secure verification and consumption of webhooks.

​
Svix Self-Hosted

For self-hosted installations, manage Svix resources directly via the Svix CLI or the Hoop CLI wrappers.

​
Event Types

Event NameDescription
dbroles.job.finishedFires when a database user role is provisioned
microsoftteams.review.createFires when a review is created
session.openFires when a session or review is opened
session.closeFires when a session ends
Create event types with: 
hoop admin create svixeventtype session.open --description 'Sent when a session or access request is created'
hoop admin create svixeventtype session.close --description 'Sent when a session finishes'
hoop admin create svixeventtype dbroles.job.finished --description 'Sent when a database role is provisioned'

​
Endpoints

# Create an endpoint
hoop admin create svixendpoint \
  --description 'My main endpoint' \
  --url https://play.svix.com/in/e_f1q1l3Dk8HzjA2bcWA7E6CeyMuL/

# Update an endpoint with event filters
hoop admin create svixendpoint ep_<endpoint_id> \
  --overwrite \
  --filters session.open,session.close \
  --description 'My main endpoint' \
  --url https://play.svix.com/in/e_f1q1l3Dk8HzjA2bcWA7E6CeyMuL/

# List endpoints
hoop admin get svixendpoint

ID           DESCRIPTION         DISABLED   VERSION   FAIL   PENDING   SENDING   SUCCESS   FILTERS        AGE
ep_2vY7...   My main endpoint    false      1         0      0         0         3         session.open   46m ago

​
Messages

# List delivery attempts
hoop admin get svixmsg

# Filter by endpoint
hoop admin get svixmsg -q endpoint_id=ep_2vY... -q limit=100

ID           ATTEMPTID       TRIGGER     STATUS    STATUSCODE   AGE
msg_2vY...   atmpt_2vY7...   scheduled   success   204          45m ago
msg_2vY...   atmpt_2vY7...   scheduled   success   204          46m ago