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

# Lifecycle Webhooks

> Register webhook endpoints and inspect delivery attempts.

Lifecycle webhooks are available from the Python SDK, CLI, and HTTP API. The
TypeScript SDK does not expose a webhook surface.

## Create a webhook

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Lifecycle

  lifecycle = Lifecycle()
  webhook = lifecycle.create_webhook(
      "https://example.com/nullspace/lifecycle",
      operations=["create", "destroy"],
      signing_secret="whsec_...",
  )
  print(webhook.id)
  lifecycle.close()
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace lifecycle webhooks create \
    --url https://example.com/nullspace/lifecycle \
    --operation create \
    --operation destroy \
    --signing-secret whsec_...
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/lifecycle/webhooks" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/nullspace/lifecycle",
      "operations": ["create", "destroy"],
      "signing_secret": "whsec_..."
    }'
  ```
</CodeGroup>

## Manage webhooks

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  webhooks = lifecycle.list_webhooks()
  webhook = lifecycle.get_webhook("wh_123")
  updated = lifecycle.update_webhook("wh_123", enabled=False)
  lifecycle.delete_webhook("wh_123")
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace lifecycle webhooks list
  nullspace lifecycle webhooks get wh_123
  nullspace lifecycle webhooks update wh_123 --disabled
  nullspace lifecycle webhooks delete wh_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/lifecycle/webhooks" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  curl "${NULLSPACE_API_URL}/v1/lifecycle/webhooks/wh_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  curl -X PATCH "${NULLSPACE_API_URL}/v1/lifecycle/webhooks/wh_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{ "enabled": false }'

  curl -X DELETE "${NULLSPACE_API_URL}/v1/lifecycle/webhooks/wh_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Deliveries

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  deliveries = lifecycle.list_webhook_deliveries("wh_123", limit=20)
  detail = lifecycle.get_webhook_delivery("wh_123", "del_123")
  print(detail.status, detail.attempts)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace lifecycle webhooks deliveries wh_123
  nullspace lifecycle webhooks delivery wh_123 del_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/lifecycle/webhooks/wh_123/deliveries?limit=20" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  curl "${NULLSPACE_API_URL}/v1/lifecycle/webhooks/wh_123/deliveries/del_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Security

Use the signing secret to verify webhook payloads in your service. Rotate the
secret by updating the webhook.

Nullspace includes delivery metadata in HTTP headers:

| Header                          | Meaning                                  |
| ------------------------------- | ---------------------------------------- |
| `x-nullspace-webhook-id`        | Webhook registration ID.                 |
| `x-nullspace-delivery-id`       | Delivery attempt group ID.               |
| `x-nullspace-event-id`          | Lifecycle event ID.                      |
| `x-nullspace-signature-version` | Signature version used for verification. |
| `x-nullspace-signature`         | Signature over the delivered payload.    |

Delivery statuses are `queued`, `in_progress`, `succeeded`, and `dead_letter`.
Inspect deliveries when a receiver returns errors or times out.

## Related

* [Lifecycle events](./lifecycle-events)
* [API Reference](../api-reference)
* [CLI reference](../reference/cli)