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

In the Apono admin portal, click your avatar at the bottom left corner, click Settings and pick Webhooks

Here you'll see all of your existing webhooks.
To create a new webhook, click Add Webhook
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.
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.
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

Fields	Description
event_type	This corresponds to the webhook trigger, representing different access request statuses
event_time	The time of the event, in epoch seconds.milliseconds
data.id	The Apono request ID
data.friendly_id	A shorter, human-readable ID. This is also the ID features in the UI
data.requester.email	The requester email
data.access_groups	List of access groups, reference using `{{#each data.access_groups}}{{integration.name}}{{/each}}` to list all integration names
data.approvals_logical_relation	This 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_units	Each 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

Invalid host: the provided URL host is incorrect.
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.

Navigate to the Webhooks page
Pick the webhook you'd like to see the history for
Click the Webhook row or use the side menu and click History
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

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:

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: