Webhook payload reference¶

When a catch hook is configured for an access request event, Permission Assist sends an HTTP POST request to the configured endpoint. This page documents the structure of that JSON payload and describes how to send a response back to Permission Assist using the callback URL.

Payload structure¶

Each webhook delivery contains a top-level envelope with delivery metadata and an event object that contains event details and the full access request.

Top-level fields¶

Field	Type	Description
`id`	string (GUID)	Unique identifier for this webhook delivery.
`createdDate`	string (ISO 8601)	Date and time the webhook was generated.
`callback`	string (URL)	URL for sending a response back to Permission Assist. Responses are logged in the Activity section of the access request. See Using the callback URL.
`event`	object	The event envelope. See Event fields.

Event fields¶

Field	Type	Description
`event.name`	string	Machine-readable event name. See Event types for all values.
`event.display`	string	Human-readable event name (for example, `Access Request Created`).
`event.description`	string	Description of the condition that triggered the event.
`event.request`	object	The access request that triggered the event. See Access request fields.

Access request fields¶

The event.request object contains the full access request at the time the event occurred.

Field	Type	Description
`event.request.id`	string (GUID)	Unique identifier of the access request.
`event.request.kind`	string	Resource type. Always `Access Request`.
`event.request.number`	integer	Sequential access request number.
`event.request.action`	string	Action type. Values: `Add`, `Change`, `Remove`, `Suspend`, `Restore`.
`event.request.status`	string	Current status. Values: `Pending`, `Open`, `Resolved`, `Completed`, `Canceled`, `Scheduled`, `Snoozed`.
`event.request.reporter`	object	The user who created the access request.
`event.request.reporter.id`	string (GUID)	Reporter identity ID.
`event.request.reporter.name`	string	Reporter display name.
`event.request.assignee`	object	The identity assigned to fulfill the request. `null` if unassigned.
`event.request.assignee.id`	string (GUID)	Assignee identity ID.
`event.request.assignee.name`	string	Assignee display name.
`event.request.target`	object	The user or group affected by this request.
`event.request.target.type`	string	Target type. Values: `User`, `Group`.
`event.request.target.name`	string	Target name (user account name or group name).
`event.request.target.nomenclature`	string	Group nomenclature. Present only when `target.type` is `Group`.
`event.request.target.affectedIdentity`	object	The identity associated with the target. `null` for group targets.
`event.request.target.affectedIdentity.id`	string (GUID)	Identity ID.
`event.request.target.affectedIdentity.kind`	string	Always `Identity`.
`event.request.target.affectedIdentity.firstName`	string	First name.
`event.request.target.affectedIdentity.lastName`	string	Last name.
`event.request.target.affectedIdentity.emailAddress`	string	Email address.
`event.request.target.affectedIdentity.type`	string	Identity type. Values: `Employee`, `ServiceAccount`, `Bot`, `VendorAccount`.
`event.request.target.affectedIdentity.title`	string	Job title.
`event.request.target.affectedIdentity.company`	string	Company name.
`event.request.target.affectedIdentity.division`	string	Division name.
`event.request.target.affectedIdentity.department`	string	Department name.
`event.request.target.affectedIdentity.office`	string	Office location.
`event.request.target.affectedIdentity.supervisorName`	string	Supervisor display name.
`event.request.target.affectedIdentity.createdDate`	string (ISO 8601)	Source system created date.
`event.request.target.affectedIdentity.updatedDate`	string (ISO 8601)	Source system updated date.
`event.request.target.affectedIdentity.firstSeenDate`	string (ISO 8601)	First import date.
`event.request.target.affectedIdentity.inactivatedDate`	string (ISO 8601)	Inactivation date. `null` if not inactivated.
`event.request.target.affectedIdentity.status`	string	Identity status. Values: `Active`, `Disabled`, `Removed`.
`event.request.target.application`	object	The application this request applies to.
`event.request.target.application.id`	string (GUID)	Application ID.
`event.request.target.application.kind`	string	Always `Application`.
`event.request.target.application.name`	string	Application name.
`event.request.target.application.priority`	string	Priority rating. Values: `None`, `Low`, `Moderate`, `High`, `Critical`.
`event.request.target.application.isArchived`	boolean	Whether the application is archived.
`event.request.target.application.lastUpdated`	string (ISO 8601)	Application last updated date.
`event.request.target.privileges`	array[object]	Privilege details for this request.
`event.request.target.privileges[].initialAccess`	string	Access level before the request. Values: `None`, `Unrestricted`, `Grant`, `Deny`, `Modify`.
`event.request.target.privileges[].requestedAccess`	string	Requested access level. Values: `None`, `Unrestricted`, `Grant`, `Deny`, `Modify`.
`event.request.target.privileges[].approvedAccess`	string	Approved access level. Values: `None`, `Unrestricted`, `Grant`, `Deny`, `Modify`.
`event.request.target.privileges[].permission`	object	Permission details.
`event.request.target.privileges[].permission.header`	string	Permission header/category.
`event.request.target.privileges[].permission.section`	string	Permission section/role.
`event.request.target.privileges[].permission.permission`	string	Permission name.
`event.request.target.privileges[].permission.description`	string	Permission description.
`event.request.target.privileges[].permission.riskRating`	string	Risk rating. Values: `None`, `Low`, `Moderate`, `High`, `Critical`.
`event.request.target.privileges[].permission.metadata`	array[object]	Permission metadata key-value pairs.
`event.request.target.privileges[].permission.metadata[].key`	string	Metadata key.
`event.request.target.privileges[].permission.metadata[].value`	string	Metadata value.
`event.request.target.privileges[].permission.value`	string	Raw permission value.
`event.request.target.privileges[].sources`	array[string]	Sources of this privilege assignment.
`event.request.target.privileges[].origins`	array[string]	Origins of this privilege assignment.
`event.request.target.metadata`	array[object]	Request metadata key-value pairs.
`event.request.target.metadata[].key`	string	Metadata key.
`event.request.target.metadata[].value`	string	Metadata value.
`event.request.scheduledStart`	string (ISO 8601)	Scheduled start date. `null` if not scheduled.
`event.request.startedOn`	string (ISO 8601)	Date work started. `null` if not started.
`event.request.approvedOn`	string (ISO 8601)	Date approved. `null` if not approved.
`event.request.resolvedOn`	string (ISO 8601)	Date resolved. `null` if not resolved.
`event.request.verifiedOn`	string (ISO 8601)	Date verified. `null` if not verified.
`event.request.completedOn`	string (ISO 8601)	Date completed. `null` if not completed.
`event.request.canceledOn`	string (ISO 8601)	Date canceled. `null` if not canceled.
`event.request.activity`	array[object]	Chronological activity log.
`event.request.activity[].createdDate`	string (ISO 8601)	Date of the activity entry.
`event.request.activity[].author`	string	Author display name.
`event.request.activity[].action`	string	Action description. `null` if not applicable.
`event.request.activity[].content`	string	Activity detail text.
`event.request.comments`	array[object]	User comments on this request.
`event.request.comments[].createdDate`	string (ISO 8601)	Date the comment was posted.
`event.request.comments[].author`	string	Comment author display name.
`event.request.comments[].content`	string	Comment text.
`event.request.relatedItems`	array[object]	Related review items and personnel events.
`event.request.relatedItems[].id`	string (GUID)	Related item ID.
`event.request.relatedItems[].kind`	string	Related item type. Values: `Review Item`, `Personnel Event`.
`event.request.relatedItems[].number`	integer	Related item sequential number.
`event.request.relatedItems[].status`	string	Related item status.
`event.request.requirements`	array[object]	Response requirements grouped by response type.
`event.request.requirements[].type`	string	Response type (for example, `Approve`, `Resolve`, `Verify`).
`event.request.requirements[].description`	string	Description of the response type.
`event.request.requirements[].rules`	array[object]	Requirement rules for this response type.
`event.request.requirements[].rules[].reason`	string	Reason for the requirement.
`event.request.requirements[].rules[].responses`	array[object]	Responders and their responses.
`event.request.requirements[].rules[].responses[].reviewer`	object	Reviewer identity reference.
`event.request.requirements[].rules[].responses[].reviewer.id`	string (GUID)	Reviewer identity ID.
`event.request.requirements[].rules[].responses[].reviewer.name`	string	Reviewer display name.
`event.request.requirements[].rules[].responses[].response`	string	Response status. Values: `Pending`, `Approved`, `Rejected`.
`event.request.accessModels`	array[object]	Access models associated with this request.
`event.request.accessModels[].id`	string (GUID)	Access model ID.
`event.request.accessModels[].name`	string	Access model name.
`event.request.accessModels[].description`	string	Access model description.
`event.request.accessModels[].willBeInEffect`	boolean	Whether this access model will be in effect after the request is fulfilled.

Event types¶

The following events can trigger a catch hook. The event.name value in the payload identifies which event occurred.

UI label	`event.name`	`event.description`
Access Request Created	`AccessRequestCreated`	Occurs when an access request is created.
Access Request Assigned	`AccessRequestAssigned`	Occurs when an access request is assigned to a person.
Access Request Approved	`AccessRequestApproved`	Occurs when an access request is approved by all required reviewers.
Access Request Provisioning	`AccessRequestProvisioning`	Occurs when a request to automate a provision step is made.
Access Request Resolved	`AccessRequestResolved`	Occurs when an access request is resolved by a provision engineer.
Access Request Reopened	`AccessRequestReopened`	Occurs when an access request is reopened for provisioning.
Access Request Completed	`AccessRequestCompleted`	Occurs when an access request is successfully completed.
Access Request Canceled	`AccessRequestCanceled`	Occurs when an access request is canceled.

Sample payload¶

The following is a sample payload for an AccessRequestCreated event.

{
  "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "createdDate": "2025-12-01T14:30:05Z",
  "callback": "https://pa.firstbankofvalkyrie.com/webhooks/callback/f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "event": {
    "name": "AccessRequestCreated",
    "display": "Access Request Created",
    "description": "Occurs when an access request is created.",
    "request": {
      "id": "a2b3c4d5-e6f7-8901-2345-6789abcdef01",
      "kind": "Access Request",
      "number": 1042,
      "action": "Remove",
      "status": "Pending",
      "reporter": {
        "id": "c4d5e6f7-a8b9-0123-4567-89abcdef0123",
        "name": "Permission Assist"
      },
      "assignee": null,
      "target": {
        "type": "User",
        "name": "rjohnson",
        "affectedIdentity": {
          "id": "d4a7e2b1-3f5c-4a8d-9e6b-1c2d3e4f5a6b",
          "kind": "Identity",
          "firstName": "Rachel",
          "lastName": "Johnson",
          "emailAddress": "rjohnson@firstbankofvalkyrie.com",
          "type": "Employee",
          "title": "Teller",
          "company": "First Bank of Valkyrie",
          "division": "Retail Banking",
          "department": "Branch Operations",
          "office": "Uptown Branch",
          "supervisorName": "Davis, Michelle",
          "createdDate": "2022-06-10T12:00:00Z",
          "updatedDate": "2025-10-15T16:30:00Z",
          "firstSeenDate": "2022-06-11T02:00:00Z",
          "inactivatedDate": null,
          "status": "Active"
        },
        "application": {
          "id": "b8c1d2e3-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
          "kind": "Application",
          "name": "Jack Henry Symitar",
          "priority": "Critical",
          "isArchived": false,
          "lastUpdated": "2025-12-01T08:45:00Z"
        },
        "privileges": [
          {
            "initialAccess": "Unrestricted",
            "requestedAccess": "None",
            "approvedAccess": "None",
            "permission": {
              "header": "Teller Operations",
              "section": "Cash Management",
              "permission": "Process Cash Advance",
              "description": "Allows processing cash advances against credit lines",
              "riskRating": "High",
              "metadata": [
                {
                  "key": "Limit",
                  "value": "$10,000"
                }
              ],
              "value": "CASH_ADVANCE_PROCESS"
            },
            "sources": ["Direct Assignment"],
            "origins": ["Import #47"]
          }
        ],
        "metadata": [
          {
            "key": "Full Name",
            "value": "Rachel Johnson"
          },
          {
            "key": "Department",
            "value": "Branch Operations"
          }
        ]
      },
      "scheduledStart": null,
      "startedOn": null,
      "approvedOn": null,
      "resolvedOn": null,
      "verifiedOn": null,
      "completedOn": null,
      "canceledOn": null,
      "activity": [
        {
          "createdDate": "2025-12-01T14:30:05Z",
          "author": "Permission Assist",
          "action": "Created",
          "content": "Access request created from review finding"
        }
      ],
      "comments": [],
      "relatedItems": [
        {
          "id": "b3c4d5e6-f7a8-9012-3456-789abcdef012",
          "kind": "Review Item",
          "number": 5421,
          "status": "Flagged"
        }
      ],
      "requirements": [
        {
          "type": "Approve",
          "description": "Approval is required before work can begin",
          "rules": [
            {
              "reason": "Supervisor approval required",
              "responses": [
                {
                  "reviewer": {
                    "id": "f7a8b9c0-d1e2-3456-7890-abcdef012345",
                    "name": "Davis, Michelle"
                  },
                  "response": "Pending"
                }
              ]
            }
          ]
        }
      ],
      "accessModels": [
        {
          "id": "c5d6e7f8-a9b0-1234-5678-9abcdef01234",
          "name": "Teller - Branch Operations",
          "description": "Standard access for teller staff in branch operations",
          "willBeInEffect": false
        }
      ]
    }
  }
}

Using the callback URL¶

Each payload includes a callback URL. After your endpoint receives a webhook, you can send a response back to Permission Assist by sending an HTTP POST request to this URL with a plain-text body.

POST https://[your-pa-server]/webhooks/callback/{id}
Content-Type: text/plain

Provisioning complete. User rjohnson removed from cash advance group.

Permission Assist logs the response body in the Activity section of the access request.

Note

The callback URL is unique to each webhook delivery. Do not reuse a callback URL from a previous delivery.

Related topics:

Add webhooks (Responsibilities tab)