Outbound Webhooks

Send Apono access requests data to ITSM, DSPM, incident response, SIEM, DevX or other internal tools

Overview

Are you working with ITSM, DSPM, incident response, SIEM, DevX or other internal tools? Do you need to sync Apono access requests data with these tools? Now you can do it easily with Apono webhooks.

This means you can automate Jira or Servicenow ticket creation, create or update events in security event management or logs tools, like Cloudflare, Datadog and Logz.io, trigger customer notifications from your Salesforce or Hubspot, and more!

Our flexible, intuitive webhooks infrastructure allows admins to set up a target URL, create the required headers, pick the authorization type the tool expects, pick triggers based on access request statuses, construct the body in JSON using Apono's access request data schema and test the connection immediately.

Once set up, every time an access request is created or transitions between statuses, a webhook will be sent to the tool of your choice.

📘

What is a webhook?

A webhook is an HTTP request, triggered by an event in a source system and sent to a destination system, often with a payload of data. Read more here

Step-by-step guide

Create a new webhook

  1. In the Apono admin portal, click your avatar at the bottom left corner, click Settings and pick Webhooks
  1. Here you'll see all of your existing webhooks.
  2. To create a new webhook, click Add Webhook
  3. Fill in the following fields:
    1. Method - We support POST, PUT or DELETE
    2. URL of the target system. Requirements:
      1. HTTPS only
      2. No custom ports
    3. The webhook body with all the data that will be sent to your target system. Base this on the schema shown on the right side of the screen.
      1. This is a customized body using a handlebars templating. The result body must be JSON.
    4. Headers - Insert any custom headers needed, for example: the authorization header, as required by the target system. Requirements:
      1. Up to 10 headers
    5. Triggers - you may pick one or more triggers. Triggers correspond to Apono access request statuses:
      • Created
      • Approved
      • Rejected
      • Granted
      • Expired
      • Failed
    6. Name - any name of your choosing. This will be displayed in the webhooks table.
    7. Status - if you save the webhook as active, it can be triggered immediately. If you prefer, you may also save it as inactive and activate it later.
  4. You may click Test to trigger a test event using your configuration. The response status (Success/Failure) will appear at the bottom of the screen. More information, including the complete request and response, will be available in a side panel opening to the right.
  5. When you're ready, click Create Webhook.

Apono data schema

Apono offers a wide variety of data fields on the Access Request. This supports a myriad of business applications and use cases.

You can find the schema in the UI, by clicking View event's payload schema next to the Body Template.

Below is an example data schema for an Apono Access Request:

{
    "event_type": "AccessRequestCreated",
    "event_time": 1696263265.851898000,
    "data": {
        "id": "123",
        "friendly_id": "AR-123",
        "requester": {
            "id": "user-1",
            "name": "User",
            "email": "[email protected]"
        },
        "justification": "I need access to this",
        "creation_date": 1696263265.852378000,
        "revocation_date": 1696266865.852380000,
        "access_flow": {
            "id": "flow-1",
            "name": "Flow 1"
        },
        "access_bundle": {
            "id": "bundle-1",
            "name": "Bundle 1"
        },
        "access_groups": [
            {
                "integration": {
                    "id": "integration-1",
                    "type": "Postgresql",
                    "name": "prod db"
                },
                "resource_types": [
                    {
                        "id": "postgresql-database",
                        "name": "Database",
                        "display_path": "Postgresql/Database"
                    }
                ],
                "access_units": [
                    {
                        "resource": {
                            "id": "res-1",
                            "name": "DB 1",
                            "path": "prod db/res-1",
                            "type": {
                                "id": "postgresql-database",
                                "name": "Database",
                                "display_path": "Postgresql/Database"
                            }
                        },
                        "permission": {
                            "id": "ReadOnly",
                            "name": "ReadOnly"
                        }
                    },
                    {
                        "resource": {
                            "id": "res-2",
                            "name": "DB 2",
                            "path": "prod db/res-2",
                            "type": {
                                "id": "postgresql-database",
                                "name": "Database",
                                "display_path": "Postgresql/Database"
                            }
                        },
                        "permission": {
                            "id": "ReadOnly",
                            "name": "ReadOnly"
                        }
                    }
                ]
            }
        ],
        "approvals_logical_relation": "AllOf",
        "approvals": [
            {
                "name": "Manager",
                "type": "Manager",
                "status": "Pending"
            },
            {
                "name": "Admins",
                "type": "Group",
                "status": "Approved",
                "approver": {
                    "id": "admin-1",
                    "name": "Admin 1",
                    "email": "[email protected]"
                }
            }
        ]
    }
}

Example fields and how to use them

📘

Apono uses handle bars templates syntax

To learn more about handle bars, click here

FieldsDescription
event_typeThis corresponds to the webhook trigger, representing different access request statuses
event_timeThe time of the event, in epoch seconds.milliseconds
data.idThe Apono request ID
data.friendly_idA shorter, human-readable ID. This is also the ID features in the UI
data.requester.emailThe requester email
data.access_groupsList of access groups, reference using {{#each data.access_groups}}{{integration.name}}{{/each}} to list all integration names
data.approvals_logical_relationThis is a field with 2 possible values: AnyOf and AllOf. It relates to the Access Flow Admin setting to enforce more than 1 approver.
data.access_groups.access_unitsEach access group contains multiple access units. Reference it using{{#each data.access_groups}}{{#each access_units}}{{resource.name}}{{/each}}{{/each}}to list all access units per access group.

Troubleshooting

  1. Invalid host: the provided URL host is incorrect.
  2. Invalid body template:
    1. The template body is not in proper JSON syntax
    2. The template body is not in valid handlebar's syntax

Invocation history

Admins can each webhook's invocation history in the Apono Admin Portal.

  1. Navigate to the Webhooks page
  2. Pick the webhook you'd like to see the history for
  3. Click the Webhook row or use the side menu and click History
  4. You can now see a list of every webhook triggered and sent from Apono:
    1. Invocation time
    2. Trigger
    3. Status: can be Success or Failure
    4. Request and Response payloads

  1. You can get more details about the request and response by clicking the specific historic run

Results

You will now see your webhook in the Webhooks table.

For each webhook:

  1. Active webhooks will be marked with a green dot, while inactive webhooks will be marked with a white dot:
  • To activate/deactivate a webhook, click the menu to the right and click Activate:

What’s Next

Create Jira tickets triggered by Apono access requests: