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

# Webhooks

> Receive signed payout lifecycle events and process retries safely.

COP By sends outbound webhook events when a BRE-B payout changes state. Configure the endpoint and
signing secret in the partner dashboard.

## Verify every request

Read the raw body before parsing JSON and calculate:

```text theme={null}
HMAC-SHA256(secret, timestamp + "." + rawBody)
```

Compare the hex digest with `X-CopBy-Signature` using a constant-time comparison. Also read:

| Header | Purpose |
| - | - |
| `X-CopBy-Timestamp` | Signature timestamp |
| `X-CopBy-Event-Id` | Stable deduplication key |
| `X-CopBy-Event-Type` | Payout lifecycle event |

Reject an invalid signature before processing the payload.

## Return quickly

Persist the event ID, enqueue your work, and return `2xx`. Duplicate event IDs must return success
without applying the event twice.

COP By retries failed deliveries after approximately 1 minute, 5 minutes, 30 minutes, 2 hours, and
12 hours.

## Reconcile

Webhooks can arrive late or more than once. Poll `GET /api/integrations/breb/payouts/{payoutId}` as a
fallback and use the current payout resource to resolve discrepancies.

> [!NOTE]
>
> `/api/breb/webhook` is the inbound Bridge-to-COP-By endpoint. Partners should not call it. Your
> integration receives the outbound `partnerPayoutStatus` webhook documented in API Reference.

> [card] [BRE-B payouts](https://docs.copby.digitalcop.shop/breb-payouts.md)
>
> Review the payout flow that produces these events.

> [card] [Errors and lifecycle](https://docs.copby.digitalcop.shop/errors-lifecycle.md)
>
> Handle terminal, recoverable, and idempotent outcomes.


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