Webhooks

This guide explains how to configure Shipit outgoing webhooks, verify deliveries, and understand the events Shipit can currently send.

What webhooks are for

Outgoing webhooks let Shipit call your endpoint whenever a supported event happens. Typical uses include:

• syncing newly booked shipments into your own system
• reacting to booking failures automatically
• updating your UI when a new tracking event arrives
• monitoring wallet credits, debits, and low-balance alerts

Supported events

Shipit currently supports these outgoing webhook events:

• shipment.booked
• shipment.failed
• shipment.tracking_event_updated
• pending_shipment.created
• pending_shipment.completed
• wallet.credited
• wallet.debited
• wallet.low_balance

Payload examples for each event are available in Event payloads and tracking statuses.

Recommended setup flow

1. Create an HTTPS endpoint in your application that accepts JSON.
2. Make the endpoint return a 2xx response after you have accepted the payload.
3. In Shipit, create a webhook and add your endpoint URL.
4. Choose the events you want to subscribe to.
5. Copy the signing secret and store it in your application.
6. Send a test webhook and verify that your endpoint receives it.
7. Review webhook history in Shipit to confirm successful delivery.

Request format

Shipit sends JSON requests with these default headers:

• Content-Type: application/json
• X-Webhook-Signature: <hmac_sha256_signature>

You can also add your own custom headers in the webhook configuration.

Signature verification

Shipit signs the raw JSON payload with HMAC-SHA256 using the webhook's signing secret. The resulting hash is sent in the X-Webhook-Signature header.

Recommended verification flow:

1. Read the raw request body exactly as received.
2. Compute an HMAC-SHA256 hash using your webhook signing secret.
3. Compare the computed hash with X-Webhook-Signature using a constant-time comparison function.
4. Reject the request if the signatures do not match.

Delivery behavior

• Any 2xx response is treated as a successful delivery.
• Any non-2xx response is treated as a failure.
• Network errors and timeouts are also treated as failures.
• Failed deliveries can be retried based on the webhook's retry settings.
• Consecutive failures can move a webhook into a review-required state.

HTTP methods and authentication

Shipit supports these outbound HTTP methods:

• GET
• POST
• PUT
• PATCH
• HEAD

POST is the recommended default unless your integration requires another method.

Shipit also supports:

• no authentication
• Basic authentication
• Digest authentication

Timeouts, retries, and payload limits

Each webhook can be configured with:

• request timeout
• connection timeout
• maximum retries
• retry strategy
• base retry delay
• maximum payload size
• request history retention

Request history

Shipit records each actual delivery attempt in webhook history, including retries. For each attempt you can review:

• request URL and HTTP method
• headers
• payload
• response status code
• response body
• duration
• error message, if the request failed before a response was received

Tracking event statuses

The shipment.tracking_event_updated event contains a tracking_event.status value from Shipit's tracking status enum. The full list is documented in Event payloads and tracking statuses.