Intro to Apono Outbound Webhooks

You can use Apono webhooks to send notifications about new access requests and changed access request statuses to your internal security, event management, and developer tools. These notifications enable you to track and log request events, and automate actions such as ticket creation or customer notifications.

This guide shows you how to configure webhooks and test them immediately.

Configure a webhook

Follow these steps to configure an Apono webhook:

1. On the Webhooks page, click Add Webhook. The Add Webhook page appears.

2. From the Method dropdown menu, select a REST method. Apono supports POST, PUT, and DELETE.

3. Enter the URL of the target system that will receive the webhook. Specify the HTTPS protocol only. Do not specify any custom ports.

4. In the Body Template field, construct a JSON body for the webhook payload.

   📘

   Click View event’s payload schema to help you construct the body. Learn about
   the schema’s data fields and view a sample schema. Learn about the schema’s data fields and view a sample schema.

5. Enter Headers as required by the target system, such as an authorization header.

6. From the Triggers dropdown menu, select one or more event triggers, which correspond to Apono access request statuses.

7. Enter a unique, alphanumeric, user-friendly Name for identifying this webhook.

8. Toggle the webhook’s Status to Active or Inactive. When active, the webhook can be triggered immediately.

9. Click Test to generate a test event to trigger your webhook. A Success or Failure response status will appear at the bottom of the page. Click Invocation Data to open a panel on the right side of the page and view the complete request and response, as well as other relevant details.

10. After verifying that the webhook works successfully, click Save Webhook.

Your newly saved webhook appears in the Webhooks table, preceded by a green dot if it is active or a white dot if it is inactive.

Troubleshoot your webhook

If your webhook test returns errors, take one of the following actions:

Use the schema to build a JSON body

The Apono schema defines the structure of the data that you can pass in the webhook payload. Apono uses the Handlebars templating language to format expressions for certain data fields.
.
You can view the full schema while constructing the JSON body as you configure the webhook.

Below is the schema, with sample values, followed by data descriptions:

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

(Top level)

data object

data.requester object

data.access_flow object

data.access_bundle object

data.access_groups object

data.access_groups.integration object

data.access_groups.resource_types object

data.access_groups.access_units object

data.access_groups.access_units.resource object

data.access_groups.access_units.resource.type object

data.access_groups.access_units.permissions object

data.approvals object

data.approvals.approver object

Manage webhooks

After creating a webhook, you can manage it.

Edit a webhook

Use the following steps to edit a webhook:

1. On the Webhooks page, locate the webhook.
2. In the row of the webhook, click ⋮ > Edit. The Edit Webhook tab appears.
3. Update the settings.
4. Test the changes.
5. Click Save Webhook.

Change the activation status

Use the following steps to change the activation status of a webhook:

1. On the Webhooks page, locate the webhook.
2. In the row of the webhook, click ⋮ > Inactivate.

   📘

   If the webhook is inactivate, Active will appear as the option.

View the invocation history

The Invocation History tab displays information about webhooks that Apono has sent:

• Date and time when the webhook was sent
• Event trigger
• Whether the webhook was successfully sent
• Request and response payloads

Use the following steps to view the invocation history:

1. On the Webhooks page, locate the webhook.
2. In the row of the webhook, click ⋮ > History. The Invocation History tab appears.

Delete a webhook

❗️

Deleting a webhook is permanent and cannot be reversed.

Use the following steps to delete a webhook:

1. On the Webhooks page, locate the webhook.
2. In the row of the webhook, click ⋮ > Delete. A confirmation popup window appears.
3. Click Yes.