---
title: "Create a signed webhook subscription"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Create a signed webhook subscription

`POST /webhooks`

## Request

- Base URL: `https://nautilinks.co/api/v1/agent`
- URL: `https://nautilinks.co/api/v1/agent/webhooks`
- Auth: HTTP bearer

Registers a public HTTPS callback for selected order events. The response reveals the signing secret once; deliveries use the Nautilinks-Signature HMAC-SHA256 header.

## Request body

- CreateWebhookRequest
  - `url` string, uri, required: Public HTTPS URL; private, loopback, and unresolved hosts are rejected.
  - `events` WebhookEvent[], required

## Response `200`

Created subscription and one-time secret.

- CreateWebhookResponse
  - `ok` true, required
  - `id` string, required
  - `url` string, uri, required
  - `events` WebhookEvent[], required
  - `secret` string, required: One-time secret; store it immediately.
  - `signing_key_derivation` 'hex(sha256(secret))', required
  - `created_at` string, required

## Other responses

- `400`: The request is syntactically or semantically invalid.
- `401`: The API key is missing, invalid, or revoked.
- `403`: The key lacks the required scope or resource ownership.
- `429`: The request quota or rolling daily order cap was reached.
- `500`: Nautilinks encountered an unexpected internal error.
- `default`: Any non-success status not listed explicitly uses the same typed error envelope.

---

[API](https://skmtc.dev/nautilinks/apis/nautilinks-agent-api.md) · [All operations](https://skmtc.dev/nautilinks/apis/nautilinks-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nautilinks/apis/nautilinks-agent-api/revisions/7a2b1a00e40c?raw)