---
title: "Create webhook"
method: POST
path: "/api/v1/external/webhooks"
tags: ["Webhooks"]
---

# Create webhook

`POST /api/v1/external/webhooks`

## Request

- Base URL: `https://api.wove.com`
- URL: `https://api.wove.com/api/v1/external/webhooks`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/wove/apis/wove-external-api/docs/api/v1/external/webhooks/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new webhook endpoint for receiving notifications.

## Example Payloads

### extraction.completed
```json
{
  "event": "extraction.completed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "document": { /* WebhookDocument object */ },
    "entityType": "shipments",
    "entityId": "1014560123456789012"
  }
}
```

### validation.completed
```json
{
  "event": "validation.completed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "jobId": "1014560123456789012",
    "entityId": "1014560123456789012",
    "entityType": "shipments",
    "documents": [ /* array of WebhookDocument objects */ ],
    "validationResult": { /* validation results */ },
    "itemsValidated": 15,
    "issuesFound": 2,
    "completedAt": "2024-01-15T10:30:00.000Z",
    "type": "cross-validation"
  }
}
```

## Request body

- CreateWebhookRequest
  - `url` string, uri, required: HTTPS URL to receive webhook notifications
  - `events` string[], required
  - `description` string

## Response `201`

Webhook created successfully

- object
  - `success` boolean
  - `data` object
    - `id` string
    - `url` string, uri
    - `events` string[]
    - `description` string
    - `isActive` boolean
    - `createdAt` string, date-time
    - `lastTriggeredAt` string, date-time
    - `secret` string: Webhook secret for signature verification

## Other responses

- `400`: Invalid request parameters

---

[API](https://skmtc.dev/wove/apis/wove-external-api.md) - [All operations](https://skmtc.dev/wove/apis/wove-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wove/apis/wove-external-api/revisions/37290e267e07?raw)