Delivery and Retries

This page covers how webhook deliveries work, including manual resends, automatic retries, and automatic endpoint disablement.

Resending Deliveries

If a webhook delivery fails, you can manually resend it using the API. This is useful for:

• Recovering from temporary endpoint outages
• Retrying after fixing a bug in your webhook handler
• Testing your endpoint with real event data

API Endpoint

POST /webhooks/v1/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/resend

Example Request

curl -X POST \
  'https://api.lynkwell.com/webhooks/v1/webhook-endpoints/we_abc123/deliveries/del_xyz789/resend' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

{
  "data": {
    "id": "del_xyz789",
    "status": "success",
    "statusCode": 200,
    "attempt": {
      "status": "success",
      "timestamp": "2024-01-15T10:35:00.000Z"
    }
  }
}

The resend operation:

• Uses the original event payload
• Generates a fresh signature with a new timestamp
• Records the attempt in the delivery's attempt history
• Returns the result immediately (synchronous)

Automatic Retries

When Lynkwell sends a webhook, it automatically retries failed deliveries using exponential backoff:

• Initial delivery: Attempted immediately when the event occurs
• Automatic retries: Up to 5 retries on failure
• Timeout: 30 seconds per request

Retry Schedule

The total retry window spans approximately 89 hours (~3.7 days) from the initial failure, giving your endpoint ample time to recover from outages.

A delivery is considered successful when your endpoint returns a 2xx status code. Any other response (or timeout) is treated as a failure and triggers the retry schedule.

Automatic Endpoint Disablement

To prevent unnecessary load from endpoints that are consistently failing, Lynkwell automatically disables webhook endpoints that have not had a successful delivery for an extended period.

Disablement Criteria

An endpoint is automatically disabled when all of the following conditions are true:

• There have been delivery attempts within the last 7 days
• There have been no successful deliveries within the last 7 days
• The endpoint was created more than 7 days ago (new endpoints get a grace period)

What Happens When an Endpoint is Disabled

When an endpoint is automatically disabled:

1. The endpoint status changes from active to inactive
2. The endpoint stops receiving new webhook events
3. Pending deliveries are removed from the retry queue
4. Existing events and delivery history are preserved for 30 days

Re-enabling a Disabled Endpoint

If your endpoint was automatically disabled, you can re-enable it once you've resolved the underlying issue:

1. Fix the issue causing delivery failures (e.g., endpoint downtime, incorrect URL, authentication problems)
2. Update the endpoint status via the API:

curl -X PATCH \
  'https://api.lynkwell.com/webhooks/v1/webhook-endpoints/we_abc123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"status": "active"}'

1. Optionally, resend any failed deliveries that occurred while the endpoint was down