> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/webhooks/events.md).

# Webhook Events

Violet publishes webhook events organized by entity type, making it easy to find and subscribe to the events relevant to your integration.

## Entity Types

Select an entity type below to view all available webhook events for that entity:

### [Order Webhooks](/prism/webhooks/events/order-webhooks.md)

Track the complete order lifecycle including placement, acceptance, shipment, delivery, refunds, cancellations, and failures.

**Events:** `ORDER_ACCEPTED`, `ORDER_UPDATED`, `ORDER_COMPLETED`, `ORDER_SHIPPED`, `ORDER_DELIVERED`, `ORDER_REFUNDED`, `ORDER_CANCELLED`, `ORDER_FAILED`

### [Merchant Webhooks](/prism/webhooks/events/merchant-webhooks.md)

Monitor merchant connections, status changes, and health check updates.

**Events:** `MERCHANT_CONNECTED`, `MERCHANT_DISCONNECTED`, `MERCHANT_ENABLED`, `MERCHANT_DISABLED`, `MERCHANT_NEEDS_ATTENTION`, `MERCHANT_COMPLETE`

### [Offer Webhooks](/prism/webhooks/events/offer-webhooks.md)

Receive notifications about product offer availability and updates.

**Events:** `OFFER_CREATED` (deprecated), `OFFER_ADDED`, `OFFER_UPDATED`, `OFFER_REMOVED`, `OFFER_DELETED`

### [Collection Webhooks](/prism/webhooks/events/collection-webhooks.md)

Track collection creation, updates, and changes to collection contents.

**Events:** `COLLECTION_CREATED`, `COLLECTION_UPDATED`, `COLLECTION_REMOVED`, `COLLECTION_OFFERS_UPDATED`

### [Sync Webhooks](/prism/webhooks/events/sync-webhooks.md)

Get notified about catalog sync operations including start, completion, and failures.

**Events:** `PRODUCT_SYNC_STARTED`, `PRODUCT_SYNC_COMPLETED`, `PRODUCT_SYNC_FAILED`, `COLLECTION_SYNC_STARTED`, `COLLECTION_SYNC_COMPLETED`, `COLLECTION_SYNC_FAILED`

### [Payout Account Webhooks](/prism/webhooks/events/payout-account-webhooks.md)

Monitor payout account lifecycle events including creation, requirements, activation, and deletion.

**Events:** `MERCHANT_PAYOUT_ACCOUNT_CREATED`, `MERCHANT_PAYOUT_ACCOUNT_REQUIREMENTS_UPDATED`, `MERCHANT_PAYOUT_ACCOUNT_ACTIVATED`, `MERCHANT_PAYOUT_ACCOUNT_DEACTIVATED`, `MERCHANT_PAYOUT_ACCOUNT_DELETED`

### [Payment Transaction Webhooks](/prism/webhooks/events/payment-transaction-webhooks.md)

Track payment capture status changes including authorization, capture, refunds, and failures.

**Events:** `PAYMENT_TRANSACTION_CAPTURE_STATUS_UPDATED`, `PAYMENT_TRANSACTION_CAPTURE_STATUS_AUTHORIZED`, `PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED`, `PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED`, `PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED`, `PAYMENT_TRANSACTION_CAPTURE_STATUS_FAILED`

### [Transfer Webhooks](/prism/webhooks/events/transfer-webhooks.md)

Monitor fund transfers to merchants including successful transfers, partial transfers, failures, and reversals.

**Events:** `TRANSFER_SENT`, `TRANSFER_PARTIALLY_SENT`, `TRANSFER_FAILED`, `TRANSFER_UPDATED`, `TRANSFER_REVERSED`, `TRANSFER_PARTIALLY_REVERSED`, `TRANSFER_REVERSAL_FAILED`

### [Recovery Case Webhooks](/prism/webhooks/events/recovery-case-webhooks.md)

Follow the recovery of commission a channel keeps under the `RETAIN` return policy, from the case opening to the last draw.

**Events:** `RECOVERY_CASE_OPENED`, `RECOVERY_CASE_GAP_REMAINING`, `RECOVERY_CASE_RECOVERED`, `RECOVERY_CASE_EXHAUSTED`

## Webhook Headers

All webhook events include standard headers for security, identification, and filtering:

### Default Headers

* `X-Violet-Hmac` - Signed HMAC for security validation
* `X-Violet-Topic` - Event topic (e.g., ORDER\_COMPLETED)
* `X-Violet-Event-Id` - Unique event ID for idempotency
* `X-Violet-Entity-Id` - Related entity ID
* `X-Violet-Entity-Length` - Entity payload size in bytes
* `X-Violet-Webhook-Id` - Webhook subscription ID

### Additional Headers

Some events include additional context-specific headers:

* `X-Violet-Order-Id` - Order ID (order, payment transaction, and transfer events)
* `X-Violet-Bag-Id` - Bag ID (order events)
* `X-Violet-Reason` - Additional context about why the event triggered (merchant events)
* `X-Violet-Event-Id-Source` - Original event ID when resending webhooks
* `X-Violet-Recovery-Event-Key` - Stable key for deduplicating recovery case events

Learn more about [webhook headers](/prism/webhooks/managing-webhook-headers.md).

## Testing Webhooks

Use the [webhook simulation tool](/prism/webhooks/simulating-webhook-events.md) to receive real example webhook payloads for testing your integration.

## Retrieving Historical Events

Need to access webhook events that were sent in the past? See [Retrieving Webhook Events](/prism/webhooks/retrieving-webhook-events.md) for API methods to fetch historical webhook event data.

## Related Documentation

* [Webhook Overview](/prism/webhooks.md) - Introduction to webhooks
* [Managing Webhooks](/prism/webhooks/managing-webhooks.md) - Configure webhook subscriptions
* [Handling Webhooks](/prism/webhooks/handling-webhooks.md) - Best practices for processing webhooks
* [Webhook Headers](/prism/webhooks/managing-webhook-headers.md) - Detailed header documentation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violet.io/prism/webhooks/events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.