Our system uses webhooks to notify external applications about important events occurring within our application.

They offer a simple and efficient way to receive real-time notifications when specific events happen in the OPX application. Instead of constantly polling our API to check for changes, webhooks allow your application to be instantly notified.

​
Available events

​
Documents controlled worksite_documents_controlled

This webhook is triggered when all documents related to a worksite have been reviewed and validated.

{
    "event": "worksite_documents_controlled",
    "timestamp": "2024-03-21T10:00:00Z",
    "data": {
        "worksite_id": 123
    }
}

​
Document generated worksite_documents_generated

This webhook is triggered when a new document is generated for a worksite.

{
    "event": "worksite_document_generated",
    "timestamp": "2024-03-21T10:00:00Z",
    "data": {
        "worksite_id": 123,
        "document_id": 456
    }
}

​
Status changed worksite_status_changed

{
    "event": "worksite_status_changed",
    "timestamp": "2024-03-21T10:00:00Z",
    "data": {
        "worksite_id": 123,
        "status": "nouveau_statut"
    }
}

​
Setup

​
Initial configuration

To start receiving webhooks, you must contact the OPX technical team. Two pieces of information will be required:

  • Receiving URL: The HTTPS URL of your endpoint that will receive all the notifications.
  • Secret key: A string of your choice that will be used to secure the communication.

​
Receiving Webhooks

To correctly receive webhooks, your endpoint must:

  • Verify the authenticity of the webhook using the Signature header.
  • Respond quickly with an HTTP status code in the 2XX or 3XX range (within 3 seconds).
  • Handle processing asynchronously if the logic takes longer to complete.

​
Security

Each webhook request includes a Signature header, which allows you to verify that the request was sent by OPX and not altered during transit.

The signature is generated using the HMAC-SHA256 algorithm with your Secret key, and is computed over the raw body of the HTTP request.

Code example in php:

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

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

// Quick response
http_response_code(200);

// Async logic

java:

Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);

byte[] hash = sha256_HMAC.doFinal(payload.getBytes());
StringBuilder result = new StringBuilder();

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

String computedSignature = "sha256=" + result.toString();

boolean matches = signature.equals(computedSignature);

​
Retry strategy

If your endpoint doesn’t respond within 3 seconds or responds with an error code, our system will implement a retry strategy:

  • 1st attempt: Retried after 10 seconds
  • 2nd attempt: Retried after 100 seconds
  • 3rd attempt: Retried after 1000 seconds