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

# Webhooks

Receive Drive API webhooks for session events and CDR forwarding, verify HMAC signatures, and handle retries safely.

## Overview

Drive API can push updates to your backend using webhooks.

We currently support two webhook types:

* [Session Events](/docs/drive-api/events): charging session lifecycle updates (`SESSION_STARTED`, `SESSION_STOPPED`, `SESSION_COMPLETE`, etc.)
* [CDR Forwarding](/docs/drive-api/cdr): charging detail records for completed sessions (available only with external clearing)

Use this page as a starting point, then open the dedicated page for the payload details.

## Delivery Behavior

All webhook requests are sent as `HTTP POST`.

General recommendations:

* Always ignore unknown fields (new fields may be added over time)
* Return a response quickly and process asynchronously if needed
* Make your processing idempotent

Delivery differences by webhook type:

* **Session Events**: sent once, without retries
* **CDR Forwarding**: retried nightly for up to 7 days if `200` is not returned in time

For CDR forwarding, the same `requestId` is reused across retries so you can detect duplicates.

## Security (HMAC Signatures)

When HMAC is enabled, webhook requests include:

* `X-HMAC-SHA512-Signature`: base64 HMAC SHA-512 signature of the raw request body
* `X-HMAC-SHA512-SignedAt`: timestamp indicating when the payload was signed

To verify:

1. Read the raw request body exactly as received.
2. Compute HMAC SHA-512 using your **CURRENT** secret key.
3. If it does not match, verify again with **NEXT** (for key rotation compatibility).
4. Reject the request if both checks fail.

For implementation examples and key rotation details, see [Verifying HMAC Signature](/docs/drive-api/verifying-hmac-signature).

## Configuration

Webhook configuration is handled with your account manager. You typically need to provide:

* webhook URL
* any custom authorization headers your endpoint expects

## Related Guides

* [Session Events](/docs/drive-api/events)
* [CDR Forwarding](/docs/drive-api/cdr)
* [Verifying HMAC Signature](/docs/drive-api/verifying-hmac-signature)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.