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:

Skulytics sends a webhook event to the registered endpoint.
The client endpoint receives the HTTP POST request.
The client validates and accepts the webhook payload.
The client immediately returns an HTTP 200 OK response.
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.