Skip to main content

PDP Sync Error Webhooks

Create a PDP sync error webhook so Permit.io notifies your system when a policy decision point (PDP) is online but cannot sync its policy data. This page is for operators who run PDPs and want an alert, for example in their own monitoring or paging tool, when a PDP falls out of sync.

How sync error notifications work​

  1. Each PDP reports its state to Permit.
  2. When a PDP reports that it is online but cannot sync, Permit retries the sync.
  3. If the sync still fails after several retries, Permit sends a POST request to the URL of the pdp_sync_error webhook you defined for the environment.

Permit triggers the webhook only for a PDP that reports it is online. A PDP that is offline sends no report, so an offline PDP does not trigger the webhook. To find PDPs that stopped reporting, use the PDP statistics API.

Prerequisites​

  • An environment API key. See Get your API key.
  • The keys or IDs of the project and environment your PDPs connect to. See Get the project and environment.
  • An endpoint that is reachable from the internet and accepts POST requests with a JSON body.

Create the webhook​

Send a POST request to https://api.permit.io/v2/projects/{project}/envs/{environment}/webhooks with type set to pdp_sync_error and url set to your endpoint. {project} and {environment} accept either keys or IDs. Replace API_SECRET_KEY with your API key.

curl \
  -H 'Authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"type": "pdp_sync_error", "url": "https://your.webhook.receiver/path/to/webhook"}' \
  'https://api.permit.io/v2/projects/{project_id}/envs/{env_id}/webhooks'

Verify the webhook​

Send a GET request with the same API key to https://api.permit.io/v2/projects/{project}/envs/{environment}/webhooks. The API returns HTTP 200. Confirm that the response includes your webhook URL.

Webhook payload​

On a sync error, Permit sends a POST request to your URL with the IDs of the organization, project, environment, and the PDPs that failed to sync:

{
    "org_id": "a40c5d1f-d889-43e9-94ea-b9b33585fc6b",
    "project_id": "405d8339-3514-403b-8c43-83ae74cfe0e9",
    "env_id": "3f967d0d-4d55-42f3-97c4-6a5455dfe4a6",
    "pdp_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"]
}
FieldDescription
org_idID of the organization (workspace)
project_idID of the project
env_idID of the environment
pdp_idsIDs of the PDPs that could not sync. Look them up with the PDP statistics API.

Example webhook receiver​

This FastAPI app receives the webhook at the /webhook path and prints the payload. Replace the print call with your alerting logic.

from uuid import UUID

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class PDPErrorWebhook(BaseModel):
    org_id: UUID
    project_id: UUID
    env_id: UUID
    pdp_ids: list[UUID]


@app.post("/webhook")
def post_webhook(webhook_data: PDPErrorWebhook):
    print(f"Got webhook with {webhook_data}")

Contents

Edit this page

Need help?