# webhooks.endpoints.create

Create an outgoing webhook endpoint with an https URL on the standard port (443) or 8443 and event subscriptions (exact names, group wildcards such as invoice.*, or *). Private and local network addresses are refused. The signing secret is returned once; replaying the same idempotencyKey returns the same response to the same person. Supply idempotencyKey.

`POST /api/v1/accounting/webhooks.endpoints.create`

Permissions: `accounting:read`, `accounting:write`, `accounting:admin` · Roles: admin · Idempotency key required

MCP tool: `accounting_webhooks_endpoints_create`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `url` | string | Yes | A full web address, starting with https://. 10–2000 characters. |
| `description` | string |  | A short description. at most 500 characters. |
| `events` | array of strings | Yes | Event types to receive: exact names such as invoice.paid, a group wildcard such as invoice.*, or * for everything. 1–100 items; each 1–80 characters. |
| `idempotencyKey` | string | Yes | Any unique text you generate once per intended change, so a retried request only happens once. Send it as the Idempotency-Key header instead if you prefer; if you send both they must match. 8–200 characters. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/webhooks.endpoints.create \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://example.com/webhooks/oatmilk",
  "events": [
    "invoice.paid"
  ]
}'
```

## Example response

```json
{
  "data": {
    "endpoint": {
      "id": "5d4c3b2a-1f0e-4d9c-8b7a-6e5f4d3c2b1a",
      "url": "https://example.com/webhooks/oatmilk",
      "description": "CRM sync",
      "events": [
        "invoice.*"
      ],
      "secret_hint": "a1B2",
      "secret_version": 1,
      "active": true,
      "failure_count": 0,
      "disabled_reason": null,
      "disabled_at": null,
      "last_delivery_at": null,
      "last_success_at": null,
      "created_by": "user_synthetic",
      "archived_at": null,
      "revision": 1,
      "created_at": "2026-09-30T14:00:00Z",
      "updated_at": "2026-09-30T14:00:00Z",
      "status": "active"
    },
    "secret": "whsec_synthetic_shown_once_store_it_now"
  }
}
```

Reference page: https://app.getoatmilk.com/docs/api/webhooks.endpoints.create