---
title: "Create a webhook endpoint"
description: "POST https://api.markitdown.ai/v1/webhooks — Create a webhook endpoint. Authenticate with x-api-key."
url: https://markitdown.ai/docs/api/create-webhook
updated: 2026-09-26
source: markitdown.ai
---

# Create a webhook endpoint

> POST https://api.markitdown.ai/v1/webhooks — Create a webhook endpoint. Authenticate with x-api-key.

## Endpoint

**POST** `/v1/webhooks` — Create a webhook endpoint

`createWebhook` is part of the Webhooks resource of the markitdown.ai API v1. Send an API key in the `x-api-key` header (or `Authorization: Bearer mdai_…`); all bodies are `application/json` unless a response lists another media type.

## Request body

`application/json` — object (required).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `eventTypes` | "conversion.completed" \| "conversion.failed"[] | yes |  |
| `url` | string | yes |  |

## Example request

**curl**

```bash
curl -X POST https://api.markitdown.ai/v1/webhooks \
  -H "x-api-key: $MARKITDOWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "eventTypes": [ "conversion.completed" ], "url": "https://example.com/report.pdf" }'
```

## Responses

- `201` Created — the signing secret is only ever returned here.

## Related

- [API reference](https://markitdown.ai/docs/api)
- [Error codes](https://markitdown.ai/docs/errors)
- [Introduction](https://markitdown.ai/docs)
- [Document Conversion APIs](https://markitdown.ai/developers)