---
sidebar_label: 'Best practices'
sidebar_position: 5
---

# Best practices for event subscriptions

Reliability, observability, and security are critical when subscribing to events. Below are some best practices to adhere to, ensuring that your system processes events efficiently and safely.

## Use the inbox pattern

Instead of processing events immediately upon receipt, store them in a durable queue or database (your "inbox") and acknowledge receiving the event quickly.

### Why?

- Prevents timeouts if processing is slow
- Allows retries and replay in case of failures
- Decouples event reception from business logic

### Example workflow:

1. Receive event
1. Validate signature
1. Store event in inbox
1. Return 200 OK to sender
1. Process events asynchronously from the inbox

## Implement idempotency to handle retries

Event delivery may be retried by the sender if delivery fails. It is therefore important to handle events in an idempotent manner.

- Use the `id` field from the CloudEvents envelope to detect duplicates.
- Handle retries gracefully: Ensure repeated deliveries do not cause duplicate actions.
- Return appropriate HTTP status codes:
    - 2xx for success
    - 4xx for permanent errors, e.g. invalid payload; these errors will *not* trigger retries
    - 5xx for temporary errors; these errors may trigger retries


## Rotate and secure signing keys

Event payloads are signed to allow verification of authenticity. In order to support key rotation, it is considered best practice to support multiple active keys to avoid downtime. Refer to the documentation on [authenticating events](authentication.md) for more information.

## Support traceability with W3C Trace Context

To enable distributed tracing across systems, event requests include W3C Trace Context headers:

- `traceparent` - Carries the trace ID and span ID for correlation
- `tracestate` - Provides vendor-specific trace information. This header is optional and might not be included with all events.

### Why it matters:

- Helps you link event processing to upstream events
- Improves observability in complex, event-driven architectures

### Best practices:

- Extract `traceparent` and `tracestate` headers from incoming requests
- Propagate these headers when making downstream calls
- Use them in your logging and monitoring tools for end-to-end traceability

### Example trace context headers:

```
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate: property=value
```

## Enforce HTTPS 

Always use HTTPS for event subscription endpoints to protect data in transit.