Skip to main content

Document Order Webhook

When a document order is completed or cancelled, G-BRIS sends a POST request to the callback_url you provided when placing the order.

This webhook allows your system to receive asynchronous updates once order processing has finished.

When It Fires​

The webhook is triggered when the order transitions to a final state:

  • COMPLETED
  • CANCELLED

Payload​

{
  "id": "d8595ad1e63dc",
  "status": "COMPLETED",
  "created_at": 1713200000,
  "finished_at": 1713201800,
  "documents": [
    {
      "entity_persistent_id": "c338d773ad8595ad1e63dc4651854e50",
      "product_code": "DE_GMBH_ANNUAL_REPORT_EN",
      "year": 2023,
      "status": "DELIVERED",
      "download_url": "https://api.gbris.com/files/d8595ad1e63dc/YAzH4SwNkpgA0h.pdf"
    },
    {
      "entity_persistent_id": "c338d773ad8595ad1e63dc4651854e50",
      "product_code": "DE_ALL_FULL_OFFICIAL_EXTRACT_HISTORICAL_EN",
      "status": "NOT_AVAILABLE"
    }
  ]
}
FieldTypeDescription
idstringThe ID of the submitted order.
statusstringOne of: COMPLETED or CANCELLED.
created_atnumberUnix timestamp of when the order was placed.
finished_atnumberUnix timestamp of when the order finished processing.
documentsarrayList of documents included in the order.

documents[] fields​

FieldTypeDescription
product_codestringThe document product code (matches original order)
yearnumber | nullThe year requested (if applicable)
statusstringDELIVERED or NOT_AVAILABLE
download_urlstring | nullFile URL, included only if status is DELIVERED

Signature Verification​

To ensure authenticity, webhook requests include a signature header:

X-GBRIS-Signature: sha256=abc123...

Verifying the Signature​

  1. Capture the raw request body as a UTF-8 string.
  2. Generate an HMAC-SHA256 digest of that string using your Bearer token as the key.
  3. Compare the result with the X-GBRIS-Signature value.

We recommend rejecting webhook requests that do not pass signature validation.

Retry Behavior​

If your webhook endpoint:

  • Returns a non-2xx status, or
  • Fails to respond within 5 seconds

…the webhook will be retried up to 3 times, at 30-minute intervals.

Best Practices​

  • Always verify the X-GBRIS-Signature header
  • Respond with a 2xx status immediately after receiving the payload
  • Handle business logic and file processing in a separate background job
  • Log delivery attempts to detect failures or duplicates