# Create a webhook

Registers a new webhook subscription for specific events.
## How webhooks work
Webhooks allow your application to receive real-time notifications when events
occur in Immofacile (e.g. a customer is created, a product is updated).
### Subscription
1. Register a webhook by providing a target URL and the event types you want to subscribe to.
2. When a subscribed event occurs, Immofacile sends an HTTP
`POST`
 request to your URL

with the event payload.

### Payload format
Every delivery is an HTTP `POST` with a JSON body (`Content-Type: application/json`,
`User-Agent: Immo-Facile: Webhook`). The envelope is the same for all events:
- `timestamp`
 — when the event occurred (ISO 8601)
- `origine`
 — the event type that triggered the notification (e.g.
`CUSTOMER_CREATE`
)
- `client_id`
 — your API client identifier
- `site_ids`
 — the sites the affected resource belongs to
- `data`
 — the identifier of the affected resource (
`customers_id`
,
`products_id`
 or
`event_id`
) and, for some events, additional details

Example:

```json
{
  "timestamp": "2026-09-11T14:30:00+02:00",
  "origine": "PRODUCT_UPDATE",
  "client_id": 12,
  "site_ids": [3],
  "data": { "products_id": 12345 }
}
```
The payload only identifies the resource: call the matching `GET` endpoint to
retrieve its current state. The content of `data` for each event is described in
the **Webhooks** section of this documentation.
### Payload formats (`format`)
- `immofacile`
 (default) — the payload described above.
- `zapier`
 — same envelope, with
`data`
 also embedding the full customer or product.

### Authentication of outgoing requests
- Use
`headers`
 to send static headers (e.g. an API key) with every delivery.
- Use
`auth_id`
 to reference an authentication configuration: Immofacile then

obtains a token and sends it as
`Authorization: Bearer <token>`
.

### Error handling and retries
- If your endpoint returns a
**4xx**
 (including
**422**
), the delivery is considered

definitively rejected and is
**not retried**
. A
`422`
 body is kept as the

rejection reason (useful for rejecting invalid data).
- If your endpoint returns a
**5xx**
, times out or is unreachable, Immofacile retries

up to
**3 times**
, with an exponentially increasing delay: about 1 minute for the

first retry, then 2 minutes, then 4 minutes.
- After 3 failed retries, the webhook is
**suspended**
: automatic retries stop and

an internal log is created. Contact support to reactivate a suspended webhook.

### Best practices
- Respond with HTTP 200 quickly to acknowledge receipt. Immofacile waits up to

**60 seconds**
 for a response before treating the delivery as failed.
- Process the payload asynchronously on your side if business logic is heavy.
- Return 422 with a descriptive body only when the data is intentionally rejected

(e.g. duplicate detection, invalid state for your system).
- Use the
`headers`
 field to include an API key for authenticating incoming requests

on your server.

### Available event types
Event types follow the pattern `RESOURCE_ACTION`:
| Family | Event types |
|  --- | --- |
| Customer | `CUSTOMER_CREATE`, `CUSTOMER_UPDATE` |
| Product | `PRODUCT_CREATE`, `PRODUCT_UPDATE` |
| Calendar | `CALENDAR_CREATE`, `CALENDAR_UPDATE`, `CALENDAR_DELETE` (requires `MODULE_IMMO_AGENDA`) |

Invalid or unavailable event types are rejected with a 422.

Endpoint: POST /hooks
Version: 1.6.0
Security: bearerAuth

## Description:

  - `How webhooks work` ()
    Webhooks allow your application to receive real-time notifications when events
occur in Immofacile (e.g. a customer is created, a product is updated).

  - `Subscription` ()
    1. Register a webhook by providing a target URL and the event types you want to subscribe to.
2. When a subscribed event occurs, Immofacile sends an HTTP
`POST`
 request to your URL

with the event payload.

  - `Payload format` ()
    Every delivery is an HTTP `POST` with a JSON body (`Content-Type: application/json`,
`User-Agent: Immo-Facile: Webhook`). The envelope is the same for all events: - `timestamp`
 — when the event occurred (ISO 8601)
- `origine`
 — the event type that triggered the notification (e.g.
`CUSTOMER_CREATE`
)
- `client_id`
 — your API client identifier
- `site_ids`
 — the sites the affected resource belongs to
- `data`
 — the identifier of the affected resource (
`customers_id`
,
`products_id`
 or
`event_id`
) and, for some events, additional details Example: ```json
{
  "timestamp": "2026-09-11T14:30:00+02:00",
  "origine": "PRODUCT_UPDATE",
  "client_id": 12,
  "site_ids": [3],
  "data": { "products_id": 12345 }
}
``` The payload only identifies the resource: call the matching `GET` endpoint to
retrieve its current state. The content of `data` for each event is described in
the **Webhooks** section of this documentation.

  - `Payload formats (format)` ()
    - `immofacile`
 (default) — the payload described above.
- `zapier`
 — same envelope, with
`data`
 also embedding the full customer or product.

  - `Authentication of outgoing requests` ()
    - Use
`headers`
 to send static headers (e.g. an API key) with every delivery.
- Use
`auth_id`
 to reference an authentication configuration: Immofacile then

obtains a token and sends it as
`Authorization: Bearer <token>`
.

  - `Error handling and retries` ()
    - If your endpoint returns a
**4xx**
 (including
**422**
), the delivery is considered

definitively rejected and is
**not retried**
. A
`422`
 body is kept as the

rejection reason (useful for rejecting invalid data).
- If your endpoint returns a
**5xx**
, times out or is unreachable, Immofacile retries

up to
**3 times**
, with an exponentially increasing delay: about 1 minute for the

first retry, then 2 minutes, then 4 minutes.
- After 3 failed retries, the webhook is
**suspended**
: automatic retries stop and

an internal log is created. Contact support to reactivate a suspended webhook.

  - `Best practices` ()
    - Respond with HTTP 200 quickly to acknowledge receipt. Immofacile waits up to

**60 seconds**
 for a response before treating the delivery as failed.
- Process the payload asynchronously on your side if business logic is heavy.
- Return 422 with a descriptive body only when the data is intentionally rejected

(e.g. duplicate detection, invalid state for your system).
- Use the
`headers`
 field to include an API key for authenticating incoming requests

on your server.

  - `Available event types` ()
    Event types follow the pattern `RESOURCE_ACTION`: | Family | Event types |
|  --- | --- |
| Customer | `CUSTOMER_CREATE`, `CUSTOMER_UPDATE` |
| Product | `PRODUCT_CREATE`, `PRODUCT_UPDATE` |
| Calendar | `CALENDAR_CREATE`, `CALENDAR_UPDATE`, `CALENDAR_DELETE` (requires `MODULE_IMMO_AGENDA`) | Invalid or unavailable event types are rejected with a 422.

## Security:

  - `bearerAuth` (unknown)
    http bearer opaque

## Request fields (application/json):

  - `url` (string, required)
    URL that will receive webhook payloads via POST.
Must be publicly accessible and respond within 60 seconds.
    Example: https://portail.example.com/webhook

  - `origines` (array, required)
    Event types to subscribe to. Each value is validated against the list
of available hook origins for the site. Invalid values return 422.
    Example: ["CUSTOMER_CREATE","CUSTOMER_UPDATE","PRODUCT_CREATE","PRODUCT_UPDATE"]

  - `headers` (object | null)
    Custom key-value headers to include in every webhook HTTP request.
Useful for authentication (e.g. API keys).
    Example: {"X-Api-Key":"secret"}

  - `auth_id` (integer | null)
    ID of a webhook auth configuration to use for request authentication.

  - `format` (string | null)
    Payload format of the deliveries. Defaults to `immofacile` when omitted.
    Enum: "immofacile", "zapier", "null"

## Response 201:

  - `201` (unknown)
    Webhook created

## Response 201 fields (application/json):

  - `data` (object)

  - `data.id` (integer)
    ID of the created webhook.

## Response 403:

  - `403` (unknown)
    Access denied. The error `code` is always `FORBIDDEN`; the `message` gives the cause:
- `You do not have permission to perform this action.`
 — the access does not

hold the API pack / right required by the endpoint.
- `Insufficient scope for this request.`
 — the resource targeted by the request

(user, customer, product, agency, transaction, ...) is outside the scope of

the authenticated access.
- `Access denied for this editor.`
 /
`Your IP address has been blocked.`
 —

editor or IP restriction.

## Response 403 fields (application/json):

  - `error` (object)

  - `error.code` (string, required)

  - `error.message` (string, required)

## Response 422:

  - `422` (unknown)
    Validation failed

## Response 422 fields (application/json):

  - `error` (object)

  - `error.code` (string)
    Enum: "VALIDATION_ERROR"

  - `error.message` (string)

  - `error.details` (array)

  - `error.details.field` (string)

  - `error.details.message` (string)

## Response 403 examples:

  - `Missing API pack / right` (unknown)

  - `Resource outside the scope of the access` (unknown)

