Skip to content

Create a webhook

Request

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

Each webhook payload contains:

  • event_type — the event that triggered the notification
  • resource_id — the ID of the affected resource
  • timestamp — when the event occurred

Error handling and retries

  • If your endpoint returns a 422, the resource is marked as errored with the reason from your response body (useful for rejecting invalid data).
  • If your endpoint returns any other error (4xx/5xx or timeout), Immofacile retries up to 3 times with exponentially increasing delay.
  • After 3 failed retries, the webhook is suspended and an internal log is created.
  • A suspended webhook stops receiving events until it is manually reactivated (via PUT /hooks/{id}).

Best practices

  • Respond with HTTP 200 within 10 seconds to acknowledge receipt.
  • 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. Common examples:

  • CUSTOMER_CREATE — New customer created
  • CUSTOMER_UPDATE — Customer modified
  • PRODUCT_CREATE — New product created
  • PRODUCT_UPDATE — Product modified
  • PRODUCT_DELETE — Product deleted

The full list of available events is validated server-side. Invalid event types will be rejected with a 422.

Security
bearerAuth
Bodyapplication/jsonrequired
urlstring, (uri)required

HTTPS URL that will receive webhook payloads via POST. Must be publicly accessible and respond within 10 seconds.

Example:"https://portail.example.com/webhook"
originesArray of stringsrequired

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"
]
headersobject or 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_idinteger or null

ID of a webhook auth configuration to use for request authentication.

formatstring or null

Custom format identifier for the payload structure.

curl -i -X POST \
  https://api-doc.immo-facile.com/_mock/openapi/hooks \
  -H 'Authorization: Bearer <YOUR_opaque_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://portail.example.com/webhook",
    "origines": [
      "CUSTOMER_CREATE",
      "CUSTOMER_UPDATE",
      "PRODUCT_CREATE",
      "PRODUCT_UPDATE"
    ],
    "headers": {
      "X-Api-Key": "my-secret-key"
    }
  }'

Responses

Webhook created

Bodyapplication/json
dataobject
Response
{
  "data": {
    "id": 42
  }
}