Create webhook

POST

/v1/webhooks

const url = 'https://api.dockt.com/v1/webhooks';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"label":"example","url":"https://example.com/webhooks/dockt","events":["document.completed"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.dockt.com/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "label": "example", "url": "https://example.com/webhooks/dockt", "events": [ "document.completed" ] }'

Creates a webhook endpoint for the active workspace. The signing secret is returned once.

Authorizations

bearerAuth
sessionCookie

Parameters

Header Parameters

idempotency-key

minLength(1)

Caller-generated retry key for duplicate-sensitive create and resend operations. Keys are scoped to the authenticated principal, method, and route and are retained for 24 hours.

string

>= 1 characters

Caller-generated retry key for duplicate-sensitive create and resend operations. Keys are scoped to the authenticated principal, method, and route and are retained for 24 hours.

Request Body^required

application/json

Creates a webhook endpoint for the active workspace.

object

label

required

maxLength(120)

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

url

required

Absolute HTTP or HTTPS URI.

string format: uri

events

required

Array<string>

Allowed values: document.completed document.failed assessment.completed

Responses

201

Envelope for a single resource response.

application/json

Envelope for a single resource response.

object

object

required

string

Allowed values: single

data

required

New webhook endpoint with one-time signing secret included in the response.

object

object

required

string

Allowed values: webhook_endpoint

required

Unique Dockt webhook endpoint identifier.

string

/^whk_[A-Za-z0-9]+$/

label

required

maxLength(120)

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

url

required

Absolute HTTP or HTTPS URI.

string format: uri

events

required

Array<string>

Allowed values: document.completed document.failed assessment.completed

status

required

Whether Dockt will deliver events to the webhook endpoint.

string

Allowed values: active disabled

delivery

required

Latest persisted delivery health for a webhook endpoint. Fields are null before the first attempt.

object

last_event_type

required

Any of:

unknown
null

Any of:

string
string

Event type delivered to a webhook endpoint.

string

Allowed values: document.completed document.failed assessment.completed

last_delivery_status

required

Any of:

string
null

Outcome of the most recent delivery attempted for a webhook endpoint.

string

Allowed values: succeeded failed

last_attempted_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

last_succeeded_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

secret_last_rotated_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

created_at

required

ISO 8601 date-time string.

string format: date-time

updated_at

required

ISO 8601 date-time string.

string format: date-time

secret

required

minLength(16)

A string at least 16 character(s) long

string

>= 16 characters

Example

{
  "object": "single",
  "data": {
    "object": "webhook_endpoint",
    "url": "https://example.com/webhooks/dockt",
    "events": [
      "document.completed"
    ],
    "status": "active",
    "delivery": {
      "last_event_type": "document.completed",
      "last_delivery_status": "succeeded",
      "last_attempted_at": "2026-08-06T09:30:00Z",
      "last_succeeded_at": "2026-08-06T09:30:00Z"
    },
    "secret_last_rotated_at": "2026-08-06T09:30:00Z",
    "created_at": "2026-08-06T09:30:00Z",
    "updated_at": "2026-08-06T09:30:00Z"
  }
}

400

The request did not match the expected schema

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/invalid-request",
  "title": "Bad request",
  "status": 400,
  "detail": "The request did not match the expected schema.",
  "instance": "req_example1042"
}

401

Problem Details response for HTTP 401. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/missing-auth",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Send a valid bearer token or browser session.",
  "instance": "req_example1042"
}

403

Problem Details response for HTTP 403. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The authenticated principal does not have the required permission.",
  "instance": "req_example1042"
}

404

Problem Details response for HTTP 404. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource was not found in the authenticated scope.",
  "instance": "req_example1042"
}

409

Problem Details response for HTTP 409. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The request conflicts with the current resource state.",
  "instance": "req_example1042"
}

422

Problem Details response for HTTP 422. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "Correct the invalid fields and send the request again.",
  "instance": "req_example1042",
  "errors": {
    "issues": [
      {
        "path": [
          "body",
          "worker",
          "nationality"
        ],
        "message": "Expected a two-letter country code."
      }
    ]
  }
}

429

Problem Details response for HTTP 429. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "detail": "Wait for the Retry-After interval before retrying.",
  "instance": "req_example1042"
}

500

Problem Details response for HTTP 500. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/internal",
  "title": "Internal server error",
  "status": 500,
  "detail": "Retry the request safely or contact Dockt support with the request ID.",
  "instance": "req_example1042"
}

Create webhook

Authorizations

Parameters

Header Parameters

Request Body required

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

500

Example

Request Body^required