This tutorial explains how the webhooks integration works: how to activate it as a customer, how events are delivered to your endpoint, and what the payload looks like.
The webhooks integration lets you receive real-time notifications when certain events happen in Pigello. As a customer, you:
- Activate the webhook integration in the Pigello customer UI.
- Configure a URL (your endpoint) that will receive
HTTP POSTrequests when events occur. - Choose which events to subscribe to from the list of subscribable event types.
Whenever any of the subscribed events occur, Pigello sends a POST request to your URL with a JSON body containing the events. Your endpoint should respond with a success status (2xx) within a timely manner, so that Pigello does not retry the delivery.
- In the Pigello customer UI, go to the Integrations section in the Configuration Center (You can find the Configuration Center by clicking on your profile in the bottom-left corner).
- Find the Pigello Webhooks integration and activate it.
- When activating the integration, fill out the following:
- Request Timeout: Enter a timeout in seconds, ranging from
10to60. If your server don't respond within that time-window, the request will be considered as failed. - Webhook URL: Enter the full URL of your endpoint (e.g.
https://your-server.com/pigello-webhooks). This is where Pigello will send POST requests. - Service event subscriptions: Select which event types you want to subscribe to. Only the events you select will be sent to your URL.
After saving, Pigello will start sending events to your endpoint when they occur.
- Method:
POST - Content-Type:
application/json - Body: A JSON
arrayof event objects. Each element in the array represents one event that was triggered.
Your endpoint should:
- Accept POST requests with
Content-Type: application/json. - Parse the body as JSON and handle the array of event objects.
- Respond with a 2xx status code (e.g.
200 OK) to acknowledge receipt. If Pigello does not receive a successful response within the configured timeout, it will retry with a backoff cycle.
Each item in the POST body is an event object with the following structure:
| Field | Type | Description |
|---|---|---|
key | UUID | Unique key for this event record. |
object_id | UUID | ID of the object that the event refers to (e.g. the role, tenant, or user that was created, updated, or deleted). |
content_type | string | Content type of the object (e.g. accounts.role, accounts.tenant). |
event_id | UUID | Corresponds to the pk value of the common.eventlog entity in the Pigello Core API that was added due to the event happening. |
event_identifiers | list of strings | The identifiers (current and potential old/deprecated identifiers of the event that is subscribed to) (e.g. accounts.role.instancecreated). |
created_at | datetime or null | When the event was created. |
Example event object:
{
"key": "550e8400-e29b-41d4-a716-446655440000",
"object_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"content_type": "accounts.role",
"event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"event_identifiers": ["accounts.role.instancecreated"],
"created_at": "2024-01-15T10:30:00.000Z"
}Example POST body (array of events):
[
{
"key": "550e8400-e29b-41d4-a716-446655440000",
"object_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"content_type": "accounts.role",
"event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"event_identifiers": ["accounts.role.instancecreated"],
"created_at": "2024-01-15T10:30:00.000Z"
},
{
"key": "550e8400-e29b-41d4-a716-446655440001",
"object_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c9",
"content_type": "accounts.tenant",
"event_id": "8d0f7780-8536-51ef-a55c-f18gd2g01bf8",
"event_identifiers": ["accounts.tenant.instanceupdated"],
"created_at": "2024-01-15T10:30:01.000Z"
}
]If your endpoint does not respond with a success status (2xx) within a timely manner, Pigello will retry the delivery using a backoff strategy. This helps ensure delivery when your service is temporarily unavailable or slow.
To avoid unnecessary retries:
- Respond quickly with
200 OK(or another 2xx) as soon as you have accepted and stored the payload. - Process the events asynchronously in your own system if needed; you do not have to finish processing before responding.
When configuring the webhook, you choose which event types to subscribe to. A complete list of subscribable events can be found when navigating to the integration in the Pigello UI.
- Activate the webhooks integration in the Pigello customer UI and set your configuration variables.
- Pigello sends POST requests with Content-Type: application/json and a JSON array of event objects.
- Each event has key, object_id, content_type, event_id, event_identifiers, and created_at.
- Respond with 2xx promptly to avoid retries; Pigello uses retries with backoff if the response is not successful in time.