# Webhooks integration

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.

## Overview

The webhooks integration lets you receive **real-time notifications** when certain events happen in Pigello. As a **customer**, you:

1. **Activate the webhook integration** in the Pigello customer UI.
2. **Configure a URL** (your endpoint) that will receive `HTTP POST` requests when events occur.
3. **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.

## Activating and configuring webhooks

1. 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).
2. Find the **Pigello Webhooks** integration and **activate** it.
3. When activating the integration, fill out the following:


- **Request Timeout:** Enter a timeout in seconds, ranging from `10` to `60`. 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.

## The POST request

- **Method:** `POST`
- **Content-Type:** `application/json`
- **Body:** A JSON `array` of 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**.


## Event object schema

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:**


```json
{
  "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):**


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

## Retries and reliability

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.


## Subscribable events

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.

## Summary

- **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.