> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byblend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I get notified when an order ships?

> Subscribe a webhook endpoint with POST /api/v1/notifications/webhooks, passing the event codes you care about — order.shipped, order.delivered, or 'all'. Blend POSTs to your URL, and can sign each delivery with an optional webhook secret.

Blend pushes events to your systems over webhooks. Create a subscription with `POST /api/v1/notifications/webhooks`, giving it your HTTPS URL and a list of `event_codes` such as `order.created`, `order.shipped`, or `order.delivered`. Pass `"all"` to receive everything. You can optionally generate a webhook secret, and Blend will sign every delivery so you can verify it came from Blend.

<Note>
  Webhooks are managed through the API. There is not yet a way to create or edit webhook subscriptions in the Blend Dashboard.
</Note>

## Set it up

<Steps>
  <Step title="See what events exist">
    ```bash theme={null}
    curl https://api.byblend.com/api/v1/notifications/events \
      -H "Authorization: Bearer {access_token}"
    ```

    Each event returns a `name`, `description`, and the `event_code` you subscribe with.
  </Step>

  <Step title="Generate a webhook secret (optional)">
    ```bash theme={null}
    curl -X POST https://api.byblend.com/api/v1/notifications/webhook-secret \
      -H "Authorization: Bearer {access_token}"
    ```

    Optional, but recommended. If you generate one, Blend sends it as `Authorization: Bearer {secret}` on every webhook delivery, so you can verify the request came from Blend. Without a secret, deliveries are unsigned.
  </Step>

  <Step title="Subscribe your endpoint">
    ```bash theme={null}
    curl -X POST https://api.byblend.com/api/v1/notifications/webhooks \
      -H "Authorization: Bearer {access_token}" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://yourcompany.com/hooks/blend",
        "event_codes": ["order.shipped", "order.delivered"]
      }'
    ```
  </Step>

  <Step title="Test before you rely on it">
    ```bash theme={null}
    curl -X POST https://api.byblend.com/api/v1/notifications/sample \
      -H "Authorization: Bearer {access_token}" \
      -H "Content-Type: application/json" \
      -d '{
        "event_code": "order.shipped",
        "webhook_url": "https://yourcompany.com/hooks/blend"
      }'
    ```

    This delivers a real, illustrative payload to your endpoint. To inspect the shape without sending anything, use `GET /notifications/sample/{event_code}`.
  </Step>
</Steps>

## What your endpoint has to do

<Warning>
  Blend requires your listener to be a valid SSL endpoint that accepts `POST` and returns a `2xx` status code **within 10 seconds**. Do your real work asynchronously — acknowledge first, process after. Deliveries that fail are retried with exponential backoff.
</Warning>

Every payload carries at minimum an `id` and a `url` that deep-links to the relevant record in the Blend Dashboard, so a notification can be turned into a clickable link for your staff with no extra lookup.

<Note>
  Prefer webhooks over polling. If you do poll, filtered list calls (`GET /orders?status=shipped`) are much cheaper than draining the full order list — see [pagination](/guides/pagination).
</Note>

## Email instead of (or alongside) webhooks

If a human needs to know rather than a system, subscribe to the same event codes by email with `PUT /api/v1/notifications/email`. Email notifications go to the address on your Blend user profile.

<CardGroup cols={2}>
  <Card title="Create a webhook subscription" icon="webhook" href="/api-reference/notifications/create-a-new-webhook-subscription">
    POST /notifications/webhooks
  </Card>

  <Card title="Get notification event types" icon="list" href="/api-reference/notifications/get-notification-event-types">
    GET /notifications/events
  </Card>

  <Card title="Generate a webhook secret" icon="key" href="/api-reference/notifications/generate-a-webhook-secret">
    POST /notifications/webhook-secret
  </Card>

  <Card title="Send a sample webhook" icon="paper-plane" href="/api-reference/notifications/send-a-sample-webhook">
    POST /notifications/sample
  </Card>
</CardGroup>