> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integrations/prism/api-reference/event-service.md).

# Event Service Overview

## Overview

The Event Service processes webhook notifications from payment processors. Instead of polling APIs for status updates, this service receives real-time events when payment states change, enabling immediate response to successful payments, failed transactions, refunds, and disputes.

**Business Use Cases:**

* **Real-time order fulfillment** - Trigger shipping when payment succeeds
* **Failed payment handling** - Retry or notify customers immediately
* **Refund tracking** - Update order status when refunds complete
* **Dispute notifications** - Alert teams when chargebacks are filed
* **Reconciliation** - Keep your system in sync with processor state

The service handles events from all supported connectors, normalizing them into a consistent format regardless of the source.

## Operations

| Operation                                                             | Description                                                                                                                                    | Use When                                               |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`Handle`](/integrations/prism/api-reference/event-service/handle.md) | Process webhook notifications from connectors. Translates connector events into standardized responses for asynchronous payment state updates. | Receiving webhook callbacks from any payment processor |

## Common Patterns

### Webhook Processing Flow

Receive and process webhook events to keep your system synchronized with payment processor state.

```mermaid
sequenceDiagram
    participant PP as Payment Provider
    participant App as Your App
    participant CS as Connector Service

    Note over PP: Payment state changes
    PP->>App: POST /webhook (event payload)
    App->>CS: 1. Handle (event data)
    CS->>CS: Verify webhook signature
    CS->>CS: Parse and normalize event
    CS-->>App: Return parsed event with type
    Note over App: Process based on event type
    alt Payment succeeded
        App->>App: Trigger order fulfillment
    else Payment failed
        App->>App: Notify customer, retry
    else Refund completed
        App->>App: Update order status
    else Dispute opened
        App->>App: Alert support team
    end
```

**Flow Explanation:**

1. **Receive webhook** - Payment processors send webhook notifications to your configured endpoint when events occur (payment success, failure, refund, dispute, etc.).
2. **Handle** - Forward the raw webhook payload to the Event Service's `Handle` RPC. The service verifies the webhook signature to ensure it's authentic, then parses and normalizes the event into a standard format regardless of which connector sent it.
3. **Process event** - Based on the returned `event_type` and `event_response`, take appropriate action in your system. The response includes the full payment/refund/dispute details so you can update your database and trigger business logic.

**Common Event Types:**

* `PAYMENT_INTENT_SUCCESS` - Payment completed successfully
* `PAYMENT_INTENT_PAYMENT_FAILED` - Payment attempt failed
* `CHARGE_REFUNDED` - Refund was processed
* `DISPUTE_CREATED` - New chargeback filed
* `DISPUTE_CLOSED` - Dispute resolved

***

### Reliable Webhook Processing

Handle webhook delivery failures and ensure events are processed even during outages.

```mermaid
sequenceDiagram
    participant PP as Payment Provider
    participant App as Your App
    participant CS as Connector Service
    participant Queue as Message Queue

    Note over PP: Payment succeeds
    PP->>App: POST /webhook (event payload)
    alt Webhook endpoint available
        App->>CS: 1. Handle (event data)
        CS-->>App: Return parsed event
        App->>Queue: Enqueue for processing
        App-->>PP: Return 200 OK
        Queue->>App: Process event
        App->>App: Update order, trigger fulfillment
    else Webhook endpoint down
        App-->>PP: Return 5xx error
        PP->>PP: Schedule retry
        Note over PP: Retry after 1 min, 5 min, 15 min...
        PP->>App: Retry webhook delivery
        App->>CS: Handle (event data)
        CS-->>App: Return parsed event
        App-->>PP: Return 200 OK
    end
```

**Flow Explanation:**

1. **Receive webhook** - Your endpoint receives the webhook POST request from the payment processor.
2. **Handle and verify** - Call the `Handle` RPC to verify the webhook signature and parse the event. Return a 200 OK response to the processor immediately to acknowledge receipt.
3. **Queue for processing** - Instead of processing synchronously, enqueue the event in a message queue (Redis, RabbitMQ, SQS, etc.). This prevents timeouts and handles retries if your processing fails.
4. **Process asynchronously** - Workers consume from the queue and process events. This decouples webhook receipt from business logic execution.

**Retry Handling:**

* Return 2xx status to stop retries
* Return 5xx status to trigger processor retry
* Processors typically retry 3-5 times with exponential backoff

***

## Security Considerations

**Webhook Verification:** The Event Service automatically verifies webhook signatures using the connector's webhook secrets. This ensures events are genuinely from the payment processor and haven't been tampered with.

**Idempotency:** Payment processors may send the same event multiple times (retries). Use the `merchant_event_id` to deduplicate events in your system.

**Timeout Handling:** Process webhooks quickly and return 200 OK. If processing takes longer than 10-30 seconds, some processors will retry. Use a queue for heavy processing.

## Next Steps

* [Payment Service](/integrations/prism/api-reference/payment-service.md) - Handle payment success/failure events
* [Refund Service](/integrations/prism/api-reference/refund-service.md) - Process refund completion events
* [Dispute Service](/integrations/prism/api-reference/dispute-service.md) - Handle dispute notification events


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hyperswitch.io/integrations/prism/api-reference/event-service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.