Purpose

This page explains the Skulytics webhook acknowledgment requirements and how clients should handle incoming webhook events.

Overview

Skulytics sends webhook events to the registered client endpoint using HTTP POST requests.

The registered webhook endpoint URL does not need to change. Existing webhook retry behavior also remains unchanged.

Clients must ensure that their webhook endpoint returns an acknowledgment immediately and does not delay the response with heavy or blocking processing.

Webhook Acknowledgment Requirement

Client endpoints must return an HTTP 200 OK acknowledgment within the allowed time window.

The webhook endpoint must:

• acknowledge the webhook request immediately
• avoid blocking the acknowledgment response with heavy or long-running processing
• return acknowledgment within 10 seconds

If acknowledgment is not received within 10 seconds, Skulytics stops waiting for that delivery attempt.

What Remains Unchanged

The following items remain unchanged:

• the registered webhook endpoint URL
• the use of HTTP POST requests
• the JSON payload format for webhook events
• the supported webhook event categories
• the existing webhook retry behavior

Required Client Action

Clients should review their webhook implementation to ensure that:

• the endpoint accepts incoming HTTP POST webhook requests
• the endpoint returns an HTTP 200 OK response immediately after receiving the webhook event
• webhook acknowledgment is not delayed by heavy processing
• acknowledgment is returned within 10 seconds

Webhook endpoints that delay acknowledgment may not work as expected.

Webhook Processing Requirements

Fast Acknowledgment

The webhook endpoint should acknowledge the request immediately after the event is received.

No Blocking Processing in the Response Flow

Heavy processing should not delay the webhook response.

Examples of processing that should not block the acknowledgment response include:

• large database operations
• long-running business logic
• external API calls that may take time
• other slow or resource-intensive processing

Acknowledgment Time Limit

Recommended webhook acknowledgment timing:

• Preferred: ≤ 1 second
• Maximum: ≤ 10 seconds

Skulytics requires webhook acknowledgments to be returned within 10 seconds. If the client endpoint does not respond within this time limit, Skulytics stops waiting for that delivery attempt.

Recommended Handling Flow

The recommended webhook handling flow is:

1. Skulytics sends a webhook event to the registered endpoint.
2. The client endpoint receives the HTTP POST request.
3. The client validates and accepts the webhook payload.
4. The client immediately returns an HTTP 200 OK response.
5. Any additional internal processing is completed after the acknowledgment step.

Example Scenario

Registered endpoint:

https://companywebsite.com/skulytics_webhooks

This endpoint URL does not need to change.

However, the webhook handler behind this endpoint must return an acknowledgment within 10 seconds and must not wait for heavy processing before responding.

Summary

Clients must ensure that their webhook endpoint:

• keeps the same registered endpoint URL
• responds immediately to incoming webhook requests
• avoids blocking the acknowledgment with heavy processing
• returns acknowledgment within 10 seconds

The webhook retry schedule remains unchanged.