Delivery and Retries

Sakneen delivers each event independently to every active destination that subscribed to its event type.

Acknowledging delivery

Return any HTTP status from 200 through 299 after the event has been durably accepted. 204 No Content is recommended.

Do not wait for slow downstream business processing. A reliable receiver usually:

1. verifies the signature;
2. validates the event envelope;
3. atomically stores the eventId and payload, or publishes them to your durable processing queue; and
4. returns 204.

Response behavior

Result	Sakneen behavior
2xx	Delivery succeeds
408	Retryable failure
429	Retryable failure
5xx	Retryable failure
Network error or timeout	Retryable failure
3xx	Permanent failure
Other 4xx	Permanent failure

Webhook requests have a 10-second request deadline. Redirects are not followed.

Sakneen performs up to five automatic HTTP attempts in one retry cycle. Sakneen manages the automatic scheduling and backoff.

After a delivery reaches failed, an authorized organization administrator can start a new retry cycle from the Developer Console.

At-least-once processing

A receiver can successfully store an event while Sakneen fails to receive its response. Sakneen then retries the same event.

Create a unique constraint on eventId and make acceptance idempotent:

CREATE TABLE sakneen_webhook_events (
  event_id VARCHAR(128) PRIMARY KEY,
  event_type VARCHAR(128) NOT NULL,
  event_version INTEGER NOT NULL,
  payload JSON NOT NULL,
  received_at TIMESTAMP NOT NULL
);

On a duplicate key, return the same successful 2xx response without applying the business change again.

The JSON event body and eventId remain the same across automatic delivery attempts. The timestamp and signature are generated for the individual HTTP attempt and can change.

Ordering

Global event ordering is not guaranteed. Different destinations and resources can progress independently.

For state synchronization:

• partition by resource.type and resource.id;
• retain the newest processed resource.version;
• ignore an event with an older or equal version after deduplication; and
• use correlationId only for tracing related events.

Monitoring

Use the destination's Deliveries section in the Developer Console to view:

• pending, delivering, delivered, failed, or cancelled status;
• lifetime and current retry-cycle attempt counts;
• HTTP status and safe error codes;
• immutable attempt history; and
• the exact outbound event JSON.

Operational checklist

• Keep the endpoint available over public HTTPS.
• Verify signatures against the raw body.
• Reject stale timestamps.
• Store signing secrets in a secret manager.
• Deduplicate by eventId.
• Return 2xx only after durable acceptance.
• Alert on sustained 5xx, timeout, and signature-verification failures.
• Preserve enough logs to search by eventId, organizationId, and correlationId.
• Test the destination after endpoint, DNS, firewall, or secret changes.