Create Webhook

POST /v1/webhooks

Register a webhook URL to receive POST requests when extraction events occur. Each user can have up to 10 active webhooks.

Try it

Test this endpoint interactively in the Swagger UI.

Authorization required

Include your API key in the Authorization header.

Request

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes
Content-Type	application/json	Yes

Body

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint that will receive webhook POST requests.
events	string[]	Yes	Events to subscribe to. At least one required. Values: "extraction.completed", "extraction.failed".

Code Examples

curl

curl -X POST https://api.docmap.io/v1/webhooks \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/docmap",
    "events": ["extraction.completed", "extraction.failed"]
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/docmap',
    events: ['extraction.completed', 'extraction.failed'],
  }),
})

const { data } = await response.json()

// IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
console.log('Signing Secret:', data.secret)
console.log('Webhook ID:', data.webhook.id)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.post(
    "https://api.docmap.io/v1/webhooks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://your-app.com/webhooks/docmap",
        "events": ["extraction.completed", "extraction.failed"],
    },
)

data = response.json()["data"]

# IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
print(f"Signing Secret: {data['secret']}")
print(f"Webhook ID: {data['webhook']['id']}")

Response

Status: 200 OK

The response body is wrapped in a data object.

WARNING

The signing secret is only returned in this response. Store it securely immediately -- it cannot be retrieved later. You need it to verify webhook signatures.

Fields

Field	Type	Description
secret	string	HMAC-SHA256 signing secret (64 hex characters). Only shown once.
webhook	object	Webhook metadata object (see below).

webhook object:

Field	Type	Description
id	string	Unique identifier for the webhook.
userId	string	ID of the user who owns the webhook.
url	string	The registered endpoint URL.
events	string[]	Events the webhook is subscribed to.
active	boolean	Whether the webhook is active. Always true for a newly created webhook.
createdAt	string	ISO 8601 timestamp of when the webhook was created.

Example

{
  "data": {
    "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "webhook": {
      "id": "webhook-abc123def456",
      "userId": "uid_a1b2c3d4e5f6",
      "url": "https://your-app.com/webhooks/docmap",
      "events": ["extraction.completed", "extraction.failed"],
      "active": true,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  }
}

Errors

Status	Code	Description
400	MAX_WEBHOOKS_REACHED	You have reached the maximum of 10 active webhooks. Delete an existing webhook before creating a new one.
401	UNAUTHORIZED	Missing, invalid, or expired API key / token.