Webhooks

OPX uses webhooks to notify your application when important events happen on your worksites. Instead of polling our API for changes, you receive an HTTP POST request as soon as an event occurs.

Setup

Creating a webhook

Webhooks are managed directly in OPX, under Settings › Developers › Webhooks (this requires the permission to manage the developer space). For each webhook, you provide:

URL: the HTTPS endpoint that will receive the notifications.
Events: at least one of the available events. A webhook only receives the events it is subscribed to.
Secret (optional, 16 characters minimum): used to sign every notification. If you leave it empty, OPX generates one for you.

The secret is displayed only once, right after the webhook is created. Store it securely: it cannot be displayed again.

You can create several webhooks, for instance to send different events to different endpoints.

Connectivity check

When a webhook is created, OPX sends a single test request to its URL to check that it is reachable:

{
    "event_id": "6f1c2b0e-8d4a-4f7e-9a51-3c2d8e7b9f10",
    "event": "webhook_ping",
    "timestamp": "2026-09-24T10:00:00.000000Z",
    "data": null
}

This request is not signed: at this point, your endpoint may not know the secret yet (especially if it was generated by OPX). Your endpoint should answer it with a 2XX status code without checking the signature. If it does not, the webhook is still created, but OPX warns that the URL could not be reached.

Payload format

Every notification shares the same envelope:

Field	Type	Description
`event_id`	string (UUID)	Unique identifier of the notification. It stays the same across retries: use it to ignore duplicates.
`event`	string	Name of the event.
`timestamp`	string (ISO 8601, UTC)	Date and time at which the event occurred.
`data`	object	Event-specific data, detailed below.

Available events

Status changed `worksite_status_changed`

Triggered when a worksite moves forward to a new status. No notification is sent when a worksite goes back to a previous status, nor when it is deleted or cancelled.

{
    "event_id": "0b8e7c5a-1f2d-4e3b-8a9c-7d6e5f4a3b21",
    "event": "worksite_status_changed",
    "timestamp": "2026-09-24T10:00:00.000000Z",
    "data": {
        "worksite_id": 123,
        "status_id": "4",
        "status": "Etape 4 : Etude finale du dossier"
    }
}

status_id is sent as a string.

Possible statuses, in workflow order:

status_id	status
1	Etape 1 : Constitution de dossier
2	Etape 2 : Etude préliminaire du dossier
3	Etape 3 : En attente des pièces finales
4	Etape 4 : Etude finale du dossier
5	Etape 5 : Contrôles
51	Etape 5bis : Contrôle contact
6	Etape 6 : A déposer auprès du PNCEE
7	Etape 7 : En attente du retour du PNCEE
8	Etape 8 : Dossier terminé

Operation updated `worksite_operation_updated`

Triggered when an operation of a worksite is updated. Several changes made to the same operation in a single action are grouped into one notification.

{
    "event_id": "9c4d2e1f-3a5b-4c6d-8e7f-1a2b3c4d5e6f",
    "event": "worksite_operation_updated",
    "timestamp": "2026-09-24T10:00:00.000000Z",
    "data": {
        "worksite_id": 123,
        "worksite_operation_id": 789
    }
}

The payload only identifies the operation: use the API to retrieve its current data.

Operation custom status changed `worksite_operation_custom_status_changed`

Triggered when a custom status is applied to an operation. Only webhooks of the entity that owns this custom status receive this event.

{
    "event_id": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
    "event": "worksite_operation_custom_status_changed",
    "timestamp": "2026-09-24T10:00:00.000000Z",
    "data": {
        "worksite_id": 123,
        "worksite_operation_id": 789
    }
}

The payload does not include the new custom status: use the API to retrieve it.

Document generated `worksite_document_generated`

Triggered when a new document is generated for a worksite.

{
    "event_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "event": "worksite_document_generated",
    "timestamp": "2026-09-24T10:00:00.000000Z",
    "data": {
        "worksite_id": 123,
        "document_id": 456
    }
}

Documents controlled `worksite_documents_controlled`

Triggered when all documents of a worksite have been reviewed and validated.

{
    "event_id": "8d9e0f1a-2b3c-4d5e-8f6a-7b8c9d0e1f2a",
    "event": "worksite_documents_controlled",
    "timestamp": "2026-09-24T10:00:00.000000Z",
    "data": {
        "worksite_id": 123
    }
}

Receiving webhooks

To receive webhooks correctly, your endpoint must:

Verify the authenticity of each notification using the Signature header (see Security).
Respond quickly, within 3 seconds, with a 2XX status code. Any other final response, or a timeout, counts as a failure.
Process asynchronously any logic that takes longer.
Ignore duplicates using event_id: a notification can be delivered more than once.

Security

Each notification includes a Signature header, which lets you verify that the request was sent by OPX and was not altered in transit. The only exception is the connectivity check, which is not signed. The signature is the HMAC-SHA256 of the raw request body, computed with your secret and encoded in lowercase hexadecimal, with no prefix. PHP:

$signature = $_SERVER['HTTP_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $payload, 'your_secret');

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Quick response
http_response_code(200);

// Async logic

Java:

Mac sha256Hmac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
sha256Hmac.init(secretKey);

byte[] hash = sha256Hmac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
StringBuilder computedSignature = new StringBuilder();

for (byte b : hash) {
    computedSignature.append(String.format("%02x", b));
}

boolean matches = MessageDigest.isEqual(
    computedSignature.toString().getBytes(StandardCharsets.UTF_8),
    signature.getBytes(StandardCharsets.UTF_8)
);

Retry strategy

If your endpoint does not respond within 3 seconds, or responds with a non-2XX status code, OPX retries the delivery. Each notification is attempted 3 times in total:

1st attempt: immediately;
2nd attempt: 10 seconds after the first failure;
3rd attempt: 100 seconds after the second failure.

After the third failed attempt, the notification is dropped.

Get Started

Energy Bonus API

Partners API

More

Setup

Creating a webhook

Connectivity check

Payload format

Available events

Status changed `worksite_status_changed`

Operation updated `worksite_operation_updated`

Operation custom status changed `worksite_operation_custom_status_changed`

Document generated `worksite_document_generated`

Documents controlled `worksite_documents_controlled`

Receiving webhooks

Security

Retry strategy

​Setup

​Creating a webhook

​Connectivity check

​Payload format

​Available events

​Status changed worksite_status_changed

​Operation updated worksite_operation_updated

​Operation custom status changed worksite_operation_custom_status_changed

​Document generated worksite_document_generated

​Documents controlled worksite_documents_controlled

​Receiving webhooks

​Security

​Retry strategy

Setup

Creating a webhook

Connectivity check

Payload format

Available events

Status changed `worksite_status_changed`

Operation updated `worksite_operation_updated`

Operation custom status changed `worksite_operation_custom_status_changed`

Document generated `worksite_document_generated`

Documents controlled `worksite_documents_controlled`

Receiving webhooks

Security

Retry strategy