> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BRP Webhooks

> Real-time event notifications for BRP Portal events

Webhook subscriptions are configured by the BRP Portal administrator. When enabled, the system pushes real-time event notifications to the registered endpoint.

<h3 id="supported-events">
  Supported Events
</h3>

| Event                              | Description                                                          |
| ---------------------------------- | -------------------------------------------------------------------- |
| `nomination.gate_closure_reminder` | Reminder that gate closure is approaching (\<8h left and has errors) |
| `nomination.file_created`          | A nominations file has been added/updated                            |
| `nomination.error_detected`        | An error/mismatch was detected in a nomination                       |
| `contract.added`                   | A new PPA contract has been added                                    |
| `customer.assigned`                | A new customer has been assigned to the BRP                          |

<h3 id="payload-format">
  Payload Format
</h3>

All webhook payloads follow this structure:

```json theme={null}
{
  "event": "nomination.error_detected",
  "timestamp": "2026-01-14T18:25:00Z",
  "data": { ... }
}
```

The `data` field contains event-specific details. The `timestamp` is the time the event occurred (ISO 8601, UTC).

<h3 id="signature-verification">
  Signature Verification
</h3>

Payloads are signed using HMAC-SHA256 with a shared secret. The signature is included in the `X-Webhook-Signature` header.

To verify a webhook payload:

1. Extract the `X-Webhook-Signature` header value from the request.
2. Compute the HMAC-SHA256 of the raw request body using your shared secret.
3. Compare the computed signature with the header value.

```bash theme={null}
# Example: verify a webhook signature
SIGNATURE=$(echo -n "$REQUEST_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

if [ "$SIGNATURE" = "$RECEIVED_SIGNATURE" ]; then
  echo "Valid signature"
fi
```

<Note>
  Always verify the webhook signature before processing the payload to ensure the request originates from Otark.
</Note>

<h3 id="best-practices">
  Best Practices
</h3>

* **Respond quickly**: Return a `200` status code within a few seconds. Process the event asynchronously if needed.
* **Handle duplicates**: Events may be delivered more than once. Use the `timestamp` and event data to deduplicate.
* **Monitor failures**: If your endpoint fails to respond, Otark will retry delivery with exponential backoff.