Webhooks

In this guide, you’ll learn how to use Webhooks to integrate a custom app with Opal. See the Custom Integrations overview to learn when to use webhooks.

You can currently only configure one webhook per organization.

Setup

Under Configuration > Organization Settings in the left panel, go to Webhooks, enter the URL for your webhook endpoint, and select Save Changes.

A signing secret will be generated. Your system should use this secret to validate the webhook’s origin. Please see this section for more details. Next, create or edit a Push-only app from the Inventory, then toggle Webhook for access changes.

The webhook endpoint is expected to reply to the HTTP POST request with an HTTP 200 response within 10 seconds of receiving the payload.

Payload samples

Opal sends different payloads depending on the event type. The following event types are supported.

Add users to resource

{
  event_ts: 1643355931,
  organization_id: 'eec5dcd9-fb0a-4726-b283-4379b524a772',
  events: [
    {
      event_type: 'USER_ADDED_TO_RESOURCE',
      resource_type: 'CUSTOM',
      user_id: '[email protected]',
      resource_id: '0eb35db24007c8148',
      access_level: 'admin'
    }
  ]
}

Remove users from resource

{
  event_ts: 1643355980,
  organization_id: 'eec5dcd9-fb0a-4726-b283-4379b524a772',
  events: [
    {
      event_type: 'USER_REMOVED_FROM_RESOURCE',
      resource_type: 'CUSTOM',
      user_id: '[email protected]',
      resource_id: '0eb35db24007c8148',
      access_level: 'admin'
    }
  ]
}

Add users to group

{
  event_ts: 1643346009,
  organization_id: 'eec5dcd9-fb0a-4726-b283-4379b524a772',
  events: [
    {
      event_type: 'USER_ADDED_TO_GROUP',
      group_type: 'CONNECTOR_GROUP',
      user_id: '[email protected]',
      group_id: '00g1835ro5hxRmpel5d7'
    }
  ]
}

Remove users from group

{
  event_ts: 1643355811,
  organization_id: 'eec5dcd9-fb0a-4726-b283-4379b524a772',
  events: [
    {
      event_type: 'USER_REMOVED_FROM_GROUP',
      group_type: 'CONNECTOR_GROUP',
      user_id: '[email protected]',
      group_id: '00g1838z8y1VJcoTG5d7'
    }
  ]
}

Add resources to group

{
  event_ts: 1643356058,
  organization_id: 'eec5dcd9-fb0a-4726-b283-4379b524a772',
  events: [
    {
      event_type: 'RESOURCE_ADDED_TO_GROUP',
      group_type: 'CONNECTOR_GROUP',
      resource_type: 'CUSTOM',
      group_id: '00g1838z8y1VJcoTG5d7',
      resource_id: '0eb35db24007c8148'
    }
  ]
}

Remove resources from group

{
  event_ts: 1643356091,
  organization_id: 'eec5dcd9-fb0a-4726-b283-4379b524a772',
  events: [
    {
      event_type: 'RESOURCE_REMOVED_FROM_GROUP',
      group_type: 'CONNECTOR_GROUP',
      resource_type: 'CUSTOM',
      group_id: '00g1838z8y1VJcoTG5d7',
      resource_id: '0eb35db24007c8148'
    }
  ]
}

Verify requests from Opal

Verify requests from Opal with confidence by checking signatures using your signing secret. Opal includes an X-Opal-Signature HTTP header on each HTTP request sent. The signature is created by combining the signing secret with the body of the request we’re sending using a standard HMAC-SHA256 keyed hash. Here is an example with Node to compute the signature using your signing secret. You can compare it against the value retrieved from the X-Opal-Signature header.

const timestamp = request.header('X-Opal-Request-Timestamp')
const signingSecret = 'SIGNING_SECRET'
const sigBaseString = 'v0:' + timestamp + ':' + JSON.stringify(request.body)
const hmac = crypto.createHmac('sha256', signingSecret);
hmac.write(sigBaseString)
console.log(hmac.digest('hex'))

Welcome

End user

Getting Started

Access Management

OpalScript

Paladin

OpalQuery

Auditing and Security

Custom Integrations

For Developers

Setup

Payload samples

Add users to resource

Remove users from resource

Add users to group

Remove users from group

Add resources to group

Remove resources from group

Verify requests from Opal

​Setup

​Payload samples

​Add users to resource

​Remove users from resource

​Add users to group

​Remove users from group

​Add resources to group

​Remove resources from group

​Verify requests from Opal

Setup

Payload samples

Add users to resource

Remove users from resource

Add users to group

Remove users from group

Add resources to group

Remove resources from group

Verify requests from Opal