Welcome to Reservix Webhooks API

Reservix Webhooks API

Introduction to Event-Driven Messaging with Reservix Webhooks

Welcome to the documentation for receiving event-driven messages using webhooks from Reservix ticketing system. Webhooks are HTTP callbacks designed to deliver notification messages when specific events occur and offer a powerful way to integrate external systems with Reservix by delivering real-time notifications about important events directly to your application.

You can subscribe to specific event types and receive payloads containing detailed information about those events. This allows your system to respond instantly to changes, such as updates, triggers, or actions taken within Reservix.

To enable webhooks, please contact us at the following email address: integration-intern@reservix.de

The following event types are supported and can trigger webhooks:

• Event

  • Triggered when the event has been created or modified.

• Event Capacity

  • Triggered when the capacity of an event has been modified.

• Customer:

  • Triggered when a customer is created, modified, or deleted.

• Order/Cancellation:

  • Triggered when an order is placed or cancelled.

• Reservation/Cancellation:

  • Triggered when a reservation is created/modified or cancelled.

• CreditNote:

  • Triggered when a credit note is created.

• PriceProfile/PriceProfileDeleted:

  • Triggered when a price profile is created/modified or deleted.

• Ticket:

  • Triggered when a ticket is created or modified.

You can subscribe to one or more of these event types based on your application’s needs.

Note

The availability of event data depends on the scope of your application. Certain scopes may limit or anonymize the information included in webhook messages. For example, in the BI/Analytics scope, customer information might be anonymized or entirely unavailable. Ensure your scope aligns with your specific use case and data requirements.

BI/Analytics scope more about the BI/Analytics scope

CRM scope more about the CRM scope

Newsletter scope more about the newsletter scope

Event Digitization more about the event digitization scope

Scope of This Documentation

This documentation will guide you through the setup and use of webhooks, includinga detailed overview of supported event types and payload structure.

Whether you’re integrating with a CRM, enabling BI/Analytics workflows, automating notifications via a Newsletter Tool or require ticket information for event digitization , Reservix webhook capabilities empower you to streamline your event-driven architecture and build responsive, scalable solutions.

Targets for Webhook Delivery

HTTPS Endpoint Webhooks can be delivered directly to an HTTPS endpoint. Each request is sent as a POST with the event payload in the body, formatted in JSON.

To ensure secure and authenticated communication, the following authentication methods are supported:

• OIDC (OpenID Connect): Securely authenticate using a trusted identity provider. The Webhook API will include a valid OIDC token in the request for the endpoint to verify.
• API Key: The Webhook API sends a predefined API key in the request headers, allowing the target system to verify the authenticity of the request.
• Header-Based Simple Authentication: A custom authentication header with a predefined token can be used for lightweight authentication.

Included HTTP Headers in Webhook Requests

Each webhook request includes the following HTTP headers to provide additional context and ensure secure communication.

Header	Description
signature	HMAC signature of the request payload, used to verify authenticity.
trace-id	Unique identifier for tracing the request across distributed systems.
traceparent	W3C Trace Context header for distributed tracing.
event-type	Type of the event contained in the payload.

Consumers of the webhook should validate and log these headers as needed for security, tracing, and event handling.

The W3C Trace Context header is a standardized way to propagate tracing information across distributed systems. It allows different services to share a unique trace ID and related metadata, enabling better observability and debugging. For more details, see the official W3C Trace Context specification: 👉 https://www.w3.org/TR/trace-context/

Metadata

Each webhook request includes a metadata field within the payload. This field provides additional context about the event and contain information such as payload/event type, timestamp, version and tracing information.

  "metadata": {
    "traceId": "19bebc7b-a2f6-4ca7-9b2e-912edc26d6d6",
    "occurredAt": "2024-12-11T14:42:55Z",
    "version": "1.0",
    "tenant": "14450",
    "type": "CUSTOMER"
  }

Versioning and Tolerant Reading

The webhook API follows semantic versioning, which ensures clear communication about changes and compatibility. The versioning format is as follows: MAJOR.MINOR (e.g., 1.0).

Breaking Changes (Major Version):

Breaking changes are introduced in major version updates (2.x, 3.x). These changes may not be backward compatible and require action from the consumers to adapt their integration. Examples of breaking changes:

• Removal of fields.
• Changes to the datatype of existing fields.
• Changes that affect the behavior or structure of the event.

Non-Breaking Changes (Minor Version):

Non-breaking changes are introduced in minor version updates (1.1.x, 1.2.x). These changes are backward compatible and do not require immediate action from the consumers. Examples of non-breaking changes:

• Addition of new fields in the payload.
• Extension of possible values for enumerated fields (enums).
• Additional metadata or optional enhancements.

Be Tolerant When Reading

It is highly recommended that consumers of the webhook API implement tolerant reading to ensure seamless handling of version changes:

• Ignore Unknown Fields: Your system should ignore any fields in the event payload that it does not recognize. This ensures compatibility when new fields are added in minor version updates.

• Handle Enum Extensions: If your system processes enum fields, it should account for the possibility of new enum values being introduced. Avoid hardcoding logic that assumes only a fixed set of values.

• Validate Only What You Need: When validating payloads, focus on the fields required for your use case rather than strictly validating the entire payload. This approach avoids rejecting valid events due to changes you don’t depend on.

• Prepare for Field Removal: While fields are rarely removed, prepare your integration to gracefully handle scenarios where a previously available field may no longer be present.

Communication of Changes

• Change Log: A detailed change log is maintained and communicated with every version update, outlining changes and potential impacts.
• Deprecation Notices: For planned breaking changes, deprecated fields or features are flagged in advance to give consumers sufficient time to adapt.
• Documentation: All changes are reflected in the official API documentation.

Delivery Guarantees and Idempotency in the Webhook API

The Webhook API ensures at least once delivery for all event notifications, making certain that every event reaches the configured target. However, this also means that the same event may be delivered more than once in some situations, such as during retries caused by network issues or target unavailability. To address this, the following mechanisms are in place:

1. Ensuring At-Least-Once Delivery The Webhook API implements robust retry logic for delivering events to the configured targets If an acknowledgment (e.g., an HTTP 2xx response for HTTPS endpoints) is not received, the event is retried until successful delivery or until a defined retry limit is reached. Events are not lost during transient failures, guaranteeing that each event is delivered to its intended destination.
2. Handling Idempotency It is the responsibility of the consumer to implement idempotency, ensuring that duplicate events do not result in undesired side effects. To assist in achieving idempotency, the Webhook API provides a traceId:

• TraceId in metadata part of the payload: Each event payload includes a traceId in its metadata, which is a unique identifier for the event. Consumers can store and track processed traceId values to identify and ignore duplicate events.

• TraceId in Headers or Attributes:

  • As a HTTP request header called trace-id and traceparent when delivering to HTTPS endpoints.

Consumers can implement idempotency by maintaining a cache or database table of processed traceId values. Example Use Case: Idempotency implementation before processing an event

1. Extract the traceId from the payload metadata or message attributes.
2. Check if the traceId has already been processed.
3. If it has, discard the event; otherwise, process it and store the traceId as processed.

Payload Signing with HMAC

To ensure the authenticity and integrity of event payloads, the Webhook API supports payload signing using HMAC (Hash-Based Message Authentication Code). This mechanism allows consumers to verify that the event payload was generated by the Webhook API and has not been tampered with during transit.

How Payload Signing Works

• Signature Generation:

When an event is triggered, the Webhook API generates a signature by hashing the event payload using a secure HMAC algorithm (e.g., HMAC-SHA256) and a shared secret key. The shared secret key is unique to each webhook configuration and must be securely stored by both the Webhook API and the consumer.

• Signature Transmission: The generated HMAC signature is sent alongside the event in one of the following ways:

The signature is included in the HTTP headers under the header name signature.

To validate the integrity and authenticity of the payload, the consumer should:

• Retrieve the shared secret key.
• Extract the signature from the X-Signature HTTP header (for HTTPS endpoints).
• Independently compute the HMAC signature of the received payload using the same algorithm and shared secret key.
• Compare the computed signature with the signature provided in the header or message attribute:
• If the signatures match, the payload is verified as authentic. If the signatures do not match, the payload should be rejected as potentially tampered with.