# createWebhookEndpoint

> Part of the MAP Audio Music API docs. Index of every page: https://map.audio/developers/music-api/llms.txt. OpenAPI document: https://map.audio/developers/music-api/openapi.json.

`POST https://api.map.audio/v1/webhook-endpoints`

Create a webhook endpoint

Subscribe a public HTTPS URL to job events: job.succeeded, job.failed and job.cancelled unless you list others, or `*` for every event. Each delivery is a signed Standard Webhooks POST (webhook-id, webhook-timestamp and webhook-signature headers: HMAC-SHA256 under the whsec_ secret, which is in this response only), retried with backoff for about 63 hours. An endpoint is disabled after three deliveries in a row run out of retries. Needs an API key or a map.audio sign-in on MAP Audio's own pages; an account has at most 10 endpoints. Free.

Auth: `Authorization: Bearer` with an API key or a map.audio access token. Not an MCP tool: Webhook endpoints hold signing secrets for your own server; set them up with an API key (POST /v1/webhook-endpoints) or with the account holder's map.audio sign-in.

## Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | A public HTTPS URL with a host name; deliveries are POSTs to it. Matches `^https://`. |
| `events` | array of "job.preview" \| "job.succeeded" \| "job.failed" \| "job.cancelled" \| "job.expired" \| "webhook.test" or "*" | no | Event types to receive; `*` receives every event. |
| `description` | string | no | At most 200 characters. |

## Example

```sh
curl -sS "https://api.map.audio/v1/webhook-endpoints" \
  -H "Authorization: Bearer $MAP_API_KEY" \
  -H "Map-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/map-audio","events":["job.succeeded","job.failed"],"description":"Render notifications"}'
```

### Request: Hear when renders end

```json
{
  "url": "https://hooks.example.com/map-audio",
  "events": [
    "job.succeeded",
    "job.failed"
  ],
  "description": "Render notifications"
}
```

### 201: Created

```json
{
  "object": "webhook_endpoint",
  "id": "whep_01M6BPRWZCT8J4PSWZ8KG7EXWV",
  "url": "https://hooks.example.com/map-audio",
  "events": [
    "job.succeeded",
    "job.failed"
  ],
  "description": "Render notifications",
  "status": "enabled",
  "createdAt": "2026-11-01T13:58:02.418Z",
  "secret": "whsec_Zm9ydHkgdHdvIGJ5dGVzIG9mIGV4YW1wbGUgc2VjcmV0IGtleSE="
}
```

### 400: Invalid request

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "url must use https; got http.",
    "param": "url",
    "retryable": false,
    "jobId": null,
    "docUrl": "https://map.audio/developers/music-api/errors#invalid_request",
    "requestId": "9a3f7c2e5b1d8f40-LHR"
  }
}
```

### 403: Webhook endpoint limit reached

```json
{
  "error": {
    "type": "entitlement",
    "code": "too_many_endpoints",
    "message": "An account may have 10 webhook endpoints; delete one with DELETE /v1/webhook-endpoints/{id} first (GET /v1/webhook-endpoints lists them).",
    "param": null,
    "retryable": false,
    "jobId": null,
    "docUrl": "https://map.audio/developers/music-api/errors#too_many_endpoints",
    "requestId": "9a3f7c2e5b1d8f40-LHR"
  }
}
```

## Responses

- `201`: The endpoint, with its secret.
- `400`: Invalid request
- `403`: Webhook endpoint limit reached
- `default`: Any other error: `error.code` names it, `error.param` the field at fault, and `error.docUrl` its entry in the error catalogue.

## Errors

- [`oauth_required`](https://map.audio/developers/music-api/errors#oauth_required)
- [`too_many_endpoints`](https://map.audio/developers/music-api/errors#too_many_endpoints)
- [`invalid_request`](https://map.audio/developers/music-api/errors#invalid_request)
- [`unsupported_media_type`](https://map.audio/developers/music-api/errors#unsupported_media_type)
- [`payload_too_large`](https://map.audio/developers/music-api/errors#payload_too_large)
- [`idempotency_key_unsupported`](https://map.audio/developers/music-api/errors#idempotency_key_unsupported)