Webhooks

Webhooks provide an event-driven alternative to polling and are a foundational part of Quinyx integrations. They enable Quinyx to send real-time notifications to your system when specific events occur, reducing API load, latency, and operational overhead.

How it works

When an event occurs inside Quinyx, such as an employee being created, a shift updated, or a schedule published, Quinyx generates an event. If your webhook subscription lists that event type, Quinyx sends an HTTPS POST request to your configured callback URL.

Subscriptions are fully manageable via the Webhooks API.

Delivery Characteristics

Quinyx delivers webhook events asynchronously, relying on a robust, managed delivery pipeline. Key characteristics include:

• Asynchronous Delivery: Events are delivered independently of the systems that generated them. This ensures operational actions inside Quinyx are never delayed by webhook processing.

• Retry Logic: If your endpoint times out or returns 401, 407, 409, 429, and 5xx error codes Quinyx retries delivery automatically following an exponential backoff strategy. Delivery attempts continue until either the message succeeds or the maximum retry window is reached. Quinyx will read the standard HTTP response header Retry-After to find out how long to wait before making a follow-up request.

• At-Least-Once Delivery: Events may be delivered more than once, and ordering is not guaranteed. Your endpoint should ensure idempotent processing.

• Subscription Isolation: Failures affecting one subscription (e.g., unreachable endpoint) do not impact other webhook subscriptions belonging to the same customer.

Delivery Requirements

To ensure reliable event delivery, your webhook endpoint must:

• Use HTTPS (TLS 1.2+)
• Respond within ~5 seconds
• Return 2xx when the event is accepted
• Handle duplicate events and out-of-order events

If your endpoint repeatedly fails or becomes unavailable, queued events may be delayed or dropped after all retry attempts have been exhausted.

Repeated errors or timeouts may lead to delivery delays or retry escalation.

Request Headers

Webhook delivery requests include a set of standard headers that allow your endpoint to identify, authenticate, and correctly process inbound events. These headers are consistently applied to all delivery attempts.

Standard Headers

• Content-Type: Always set to application/cloudevent+json.
• Content-Length: Size of the payload in bytes.
• User-Agent : Always set to Amazon/EventBridge/ApiDestinations.

Authorization Headers

If your webhook subscription includes authorization, one of the following appears:

• Authorization: Basic <base64> (Basic Auth)
• Authorization: Bearer <token> (OAuth client credentials)
• X-API-Key: <api-key> (API key)

Event Payload Structure

Quinyx webhook events follow the CloudEvents specification, providing a consistent and interoperable event envelope for all event deliveries. This structure ensures predictable fields, strong typing, and clear versioning as your integration evolves.

Events Attributes

Deprecation Attributes (Optional)

These fields help you manage the lifecycle of event types:

Example

{
  "specversion": "1.0",
  "type": "events.webhooks.ping.v1",
  "source": "api.eu.quinyx.com",
  "datacontenttype": "application/json",
  "id": "2b0b3a75-a015-4391-8ecc-4e02aa33f714",
  "time": "2025-11-27T12:00:00Z",
  "data": {
    "ping": "pong"
  },
  "deprecated": true,
  "deprecationfrom": "2025-11-01T00:00:00Z",
  "deprecationsunset": "2026-11-01T00:00:00Z"
}

Security and Authorization

Webhook endpoints must be secured with HTTPS, and Quinyx supports attaching authorization headers to outbound webhook requests. These credentials are automatically included with each event delivery attempt.

Supported authorization methods include:

API Key Authentication

Quinyx adds a static API key to a X-API-Key header. Useful for gateways, proxies, and lightweight services.

Basic Authentication

Quinyx includes your provided username and password in the Authorization: Basic header.

OAuth Client Credentials

Quinyx can fetch OAuth access tokens using the client credentials flow and include them in webhook deliveries. When this method is configured, the Authorization: Bearer <access_token> header is added to each request.

The token is automatically refreshed when:

• 401 or 407 response is returned.
• Proactively during an invocation, if the token is about to expire.

This approach is useful for endpoints that require short-lived tokens, want to avoid managing static secrets, or integrate with enterprise identity systems.

All OAuth configuration details (e.g.: client ID, client secret) are stored securely and only returned at creation time.

Failure Handling

If your endpoint is unreachable, slow, or responds with errors:

• Quinyx retries deliveries using exponential backoff
• Events are retried for a limited time
• Events eventually become marked as undeliverable

Best Practices

• Keep your endpoint fast
  • Delegate processing work to background jobs and quickly return 2xx status code
• Implement idempotency
  • Because delivery is at-least-once, duplicates can occur. Your handler must ignore or safely handle duplicates
• Implement security
  • Because webhook deliveries originate from outside your network, you should always authenticate inbound requests to ensure that only Quinyx can invoke your webhook endpoint.
  • Without proper authorization controls, malicious actors could "spoof" webhook calls and push forged data into your systems, trigger unintended workflows, or exploit your infrastructure.
• Watch for deprecated events
  • Event types may be deprecated over time. Monitor deprecated events by checking the deprecated field and ensure that you are not relying on events scheduled for removal.