Webhooks

Receive real-time event notifications from ALPHA in your system.

This section covers the webhook features currently available in production.

Webhooks let ALPHA send event notifications to your HTTPS endpoint when business events occur.

Before you start

  • Configure webhooks in the ALPHA Portal.

  • Ensure your endpoint is publicly reachable over HTTPS.

  • Store your webhook secret securely. ALPHA portal shows it once at creation and never again.

Important

Process webhook deliveries asynchronously in your system. Return a fast 2xx response after you have durably accepted the event, then do the the processing background. This minimises retries.

Quick start

  1. Register an endpoint in the ALPHA Portal. See Endpoint Configuration.

  2. Subscribe to the event types you need. See Events for the current list.

  3. Verify webhook-signature (Standard Webhooks) before processing the payload. See Security.

  4. Handle events idempotently using the event id.

  5. Return 2xx quickly after accepting the event.

Supported event types

ALPHA currently publishes the following event type:

  • packing_instructions.ready — sent when an order’s packing instructions are ready to download.

See Events for the full envelope and per-event data fields.

Delivery flow

  1. You register an endpoint in the ALPHA Portal and subscribe to events.

  2. ALPHA sends an HTTP POST request to your endpoint when the event occurs.

  3. ALPHA retries transient failures up to 4 total attempts. See Deliveries for the schedule.

Scope and isolation

  • Endpoints are scoped to your group.

  • Only active endpoints subscribed to the event receive notifications.

  • Delivery history is available in the ALPHA Portal.

Endpoint requirements

  • Publicly reachable HTTPS URL

  • Accepts HTTP POST with a JSON body

  • Responds within 10 seconds

  • Returns 2xx once the event has been accepted

Tip

Keep your handler idempotent from day one. Retries can happen for transient failures, network issues, or downstream timeouts.