Webhooks

Learn how to configure webhooks to push changes on access requests.

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 in the left panel, go to the Webhooks tab, enter the URL for your webhook endpoint (and optionally provide a custom PEM-encoded TLS CA certificate if your endpoint uses an internal CA), 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, 201, or 202 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

json

{
  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

json

{
  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

json

{
  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

json

{
  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

json

{
  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

json

{
  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'
    }
  ]
}

​

Add groups to group

json

{
  event_ts: 1643356120,
  organization_id: 'eec5dcd9-fb0a-4726-b283-4379b524a772',
  events: [
    {
      event_type: 'GROUP_ADDED_TO_GROUP',
      group_type: 'CONNECTOR_GROUP',
      member_group_type: 'CONNECTOR_GROUP',
      group_id: '00g1838z8y1VJcoTG5d7',
      member_group_id: '00g1835ro5hxRmpel5d7'
    }
  ]
}

​

Remove groups from group

json

{
  event_ts: 1643356150,
  organization_id: 'eec5dcd9-fb0a-4726-b283-4379b524a772',
  events: [
    {
      event_type: 'GROUP_REMOVED_FROM_GROUP',
      group_type: 'CONNECTOR_GROUP',
      member_group_type: 'CONNECTOR_GROUP',
      group_id: '00g1838z8y1VJcoTG5d7',
      member_group_id: '00g1835ro5hxRmpel5d7'
    }
  ]
}

​

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 timestamp and the raw HTTP request body using a standard HMAC-SHA256 keyed hash.

Here is an example with Node to compute the signature using your signing secret and raw request body (request.rawBody). You can compare it against the value retrieved from the X-Opal-Signature header.

js

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