Skip to main content

Configure Webhooks

This guide will help you configure webhooks for your Permit Elements. A webhook is an HTTP request, triggered by a meaningful event that needed to be notified. The Webhooks carry data in 'payloads', which are sent to a webhook URL, essentially an endpoint where your API can accept data.

Configure your webhook​

With most of the Permit Elements types, you will get the option to configure a webhook to stay informed of the actions that are performed by the end users, such as creating a new user, approving or denying an Approval/Access request, etc.

Webhook

EXAMPLE

The User Management Element's webhook provides an array of functionalities. For example, you can leverage it to receive notifications each time a new user is created in your system, or to initiate the sending of a welcome message to recently invited users.

Setting Up the URL Endpoint​

Before setting up a URL endpoint, it's important to note that the URL endpoint is the URL to which the webhook delivers data each time an event occurs. This endpoint should be set up on your server or a third-party service, depending on your preference.

Create the Endpoint​

Create a new endpoint on your webhook server or within your chosen third-party service. This is often a case of creating a new URL route. For example, /new-user-created or /request-approval.

Implement Webhook Handling​

Your endpoint needs to be able to receive POST requests, as webhooks will typically send data via this method. This means your endpoint needs to be set up to read the payload from incoming POST requests and then process it as required. This usually involves parsing JSON, although the exact format may vary.

The expected payload of the webhook will include different fields, depending on the type of event that triggered the webhook.

Here is an example for the payload of a webhook that is triggered when a new user is created:

{
    "email": "example@gmail.com",
    "role": "admin",
    "tenant_key": "default",
    "permission_level": "LEVEL_3"
    "type: "create_user"
 }

Secure Your Endpoint​

Webhooks contain data, and you should ensure it's secure from potential malicious use. Within the Permit configuration screen, we provide a input box so you can enter your secret, and use it to validate incoming data. This will ensure that the data is coming from a trusted source. Also, ensure your endpoint uses HTTPS, encrypting data in transit.

Webhook

Respond to the Webhook​

After receiving a POST request, it's good practice to send a 200 HTTP status code to acknowledge receipt of the data. If your endpoint fails to do this, the webhook may consider the delivery a failure and retry, causing unnecessary traffic.

Webhook Schemas​

User Management - Create User​
{
    email: str,
    tenant_key: str,
    role: str,
    permission_level: str,
    type: ElementsWebhookType = "create_user"
}
User Management - Invite User​
{
    email: str
    role: str
    tenant_id: str
    type: ElementsWebhookType = "invite_user"
}
User Management - Assign Role to User​
{
    user_id: str
    tenant_id: str
    role: str
    permission_level: str
    type: ElementsWebhookType = "role_assignment"
}
Access Request Webhook​
{
    requesting_user_id: str,
    access_request_details: {
        tenant: str
        resource: str
        resource_instance: str
        action: str
    },
    reason: str | None,
    status: RequestStatus,
    reviewer_user_id: str | None,
    reviewer_comment: str | None
}
Operation Approval Webhook​
{
    requesting_user_id: str,
    operation_approval_details: {
        tenant: str
        resource: str
        resource_instance: str
    },
    reason: str | None,
    status: RequestStatus,
    reviewer_user_id: str | None,
    reviewer_comment: str | None
}

Contents