Overview

Webhooks allow your application to receive real-time notifications when events happen in Deliverty Hub. Instead of polling the API for changes, you register a URL and Deliverty Hub sends an HTTP POST request to that URL whenever a subscribed event occurs — such as a task being created, a status change, or a payment being completed.

This push-based model is more efficient than polling and ensures your system reacts to changes within seconds.

Creating a Subscription

To start receiving webhooks, you create a webhook subscription that specifies:

• URL — The HTTPS endpoint on your server that will receive webhook payloads.
• Events — A list of event patterns to subscribe to. You can use exact event names (e.g., task.created) or wildcards (e.g., task.*) to match multiple events.
• Custom headers (optional) — Additional HTTP headers to include in every delivery, such as an Authorization bearer token for your endpoint.
• Timeout (optional) — Request timeout in milliseconds. Defaults to 5000 ms (5 seconds).
• Max retries (optional) — Maximum retry attempts for failed deliveries. Defaults to 3.

When a subscription is created, Deliverty Hub automatically generates a signing secret in the format whsec_<random_base64url_string>. This secret is used to sign every webhook payload so your server can verify the request is authentic. Store this secret securely — it is only shown once at creation time.

Payload Structure

Every webhook delivery sends a JSON payload with the following structure:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "task.status.changed",
  "timestamp": "2026-02-16T14:30:00.000Z",
  "organizationId": 42,
  "data": {
    "task": {
      "id": 1234,
      "code": "TSK-00456",
      "name": "Delivery to Downtown",
      "status": "IN_TRANSIT",
      "taskType": "DELIVERY",
      "courierType": "INTERNAL",
      "customerId": 89,
      "agentId": 12,
      "organizationId": 42,
      "createdAt": "2026-02-16T13:00:00.000Z",
      "updatedAt": "2026-02-16T14:30:00.000Z"
    },
    "oldStatus": "ACCEPTED",
    "newStatus": "IN_TRANSIT",
    "timestamp": "2026-02-16T14:30:00.000Z"
  },
  "apiVersion": "1.0"
}

Field	Type	Description
id	string (UUID)	Unique identifier for this specific webhook delivery. Use for idempotency checks.
event	string	The dot-separated event name that triggered this webhook (e.g., task.created).
timestamp	string (ISO 8601)	The time the event occurred, in ISO 8601 format.
organizationId	number	The ID of the organization that the event belongs to.
data	object	The event-specific payload. Contents vary by event type — see Event Reference.
apiVersion	string	The API version of the webhook payload format. Currently "1.0".

Delivery Headers

Each webhook HTTP request includes the following headers:

Header	Example Value	Description
Content-Type	application/json	The payload is always JSON-encoded.
X-Webhook-Signature	t=1708099800,v1=5a3c1e...	HMAC-SHA256 signature for payload verification. See Signature Verification.
X-Webhook-Id	a1b2c3d4-e5f6-...	Unique delivery ID (matches the id field in the payload). Use for deduplication.
X-Webhook-Timestamp	1708099800	Unix timestamp (seconds) when the signature was generated.
User-Agent	Deliverty-Webhook/1.0	Identifies the request as coming from Deliverty Hub.

Any custom headers you configured on the subscription are also included in every delivery.

Retry Logic

If your endpoint returns a non-2xx HTTP status code, times out, or is unreachable, Deliverty Hub will automatically retry the delivery using exponential backoff.

Parameter	Value	Description
Max retries	3 (default)	Maximum number of retry attempts after the initial delivery fails.
Backoff formula	min(1000 * 2^attempt, 60000)	Exponential backoff with a cap. Delay doubles with each attempt.
Request timeout	5000 ms (default)	If your endpoint does not respond within this time, the delivery is considered failed.

The retry schedule works out to the following delays:

Attempt	Delay	Calculation
Retry 1	1 second	min(1000 * 2^0, 60000) = 1000 ms
Retry 2	2 seconds	min(1000 * 2^1, 60000) = 2000 ms
Retry 3	4 seconds	min(1000 * 2^2, 60000) = 4000 ms

Delivery Statuses

Every webhook delivery attempt is logged with one of the following statuses:

Status	Value	Description
SUCCESS	success	Your endpoint returned an HTTP 2xx response. The delivery is complete.
PENDING_RETRY	pending_retry	The delivery failed but has not yet exceeded the maximum retry count. A retry is scheduled.
FAILED	failed	The delivery failed and all retry attempts have been exhausted.
IN_PROGRESS	in_progress	The webhook is currently being delivered to your endpoint.

Best Practices

• Respond quickly. Return a 200 OK as soon as you receive the payload. Process the webhook asynchronously if your handler requires time-consuming operations (e.g., database writes, third-party API calls).
• Use idempotency. Store the X-Webhook-Id (or the payload id) and check for duplicates before processing. Retries may deliver the same event more than once.
• Verify signatures. Always validate the X-Webhook-Signature header to confirm the request originated from Deliverty Hub. See Signature Verification.
• Use HTTPS. Your webhook endpoint should always use HTTPS to protect payloads in transit.
• Handle retries gracefully. If a retry arrives for an event you have already processed, acknowledge it with a 200 response without reprocessing.
• Monitor delivery logs. Use the webhook delivery logs in the dashboard or API to monitor success rates, failure reasons, and response times.