Webhooks

Configure and receive events for actions users are taking.

Introduction

Whenever a user takes an action at Runops, we send events to a third party provider, that will take care of delivering this events to your own endpoint.

This can be used to build your custom dashboards or analytics upon this data.

Webhooks are delivered via HTTPS requests. To receive them, you have to provide a valid URL that accepts a POST request. You must be able to receive, parse, and validate those requests.

We use svix as our webhooks provider, and you don’t need to create an account.

Receiving webhooks

As an admin, go to our portal, on settings page and click Webhooks Configuration. You will be redirected to the svix App Portal, where you can setup your endpoint.

Check the provider docs on how to configure one or more endpoints to receive the events.

Validating the HTTP requests

You must be sure that the request came from the trusted provider to avoid impersonation and replay attacks. You can do this validating the request signature. In the endpoint configuration page, you can find the signing secret.

Use that signature secret to validate the request. Do not share this secret with anyone.

Check how to validate the signature.

Types of events

The following events are available to be delivered as webhooks. All events are wrapped in the following strucuture:

plain text
{
  "type": "string",
  "data": {...}
}

Each event will contain different data structure, as following:

task.created

plain text
{
  "type": "task.created",
  "data": {
    "id" 123,
    "type": "mysql",
    "tags": "my-tags",
    "redact": "all",
    "status": "pending-review",
    "script_b64": "b64 script",
    "target": {"name": "my-target"},
    "user": {"email": "user@my-org.io"},
    "review": {
      "type": "team",
      "groups": "finance,report,CTO"
    }
  }
}

task.approved

plain text
{
  "type": "task.approved",
  "data": {
    "id": 123,
    "target": {"name": "my-target"},
    "review": {
      "reviewer": "reviewer@my-org.io",
      "group": "CTO"
    }
  }
}

task.rejected

plain text
{
  "type": "task.rejected",
  "data": {
    "id": 123,
    "target": {"name": "my-target"},
    "review": {
      "reviewer": "reviewer@my-org.io",
      "group": "CTO"
    }
  }
}

task.success

plain text
{
  "type": "task.success",
  "data": {
    "id": 123,
    "elapsed-time-ms": 904
  }
}

task.failure

plain text
{
  "type": "task.failure",
  "data": {
    "id": 123,
    "elapsed-time-ms": 904
  }
}