# Create Webhook (https://webmetic.de/docs/api/referenz/webhooks/webhooks-post)

## POST /webhooks

Register a URL that receives events (subscribe).

- `url`: https only, no credentials in the URL, a public host. A URL change is a new endpoint.
- `events`: one or more of company.identified, company.returned, company.intensive_visit, segment.entered.
- `websites`: websites of your account; all of them when omitted.
- `segment_id`: required for segment.entered; the segment's website must be among the websites.
- `headers`: up to 3 custom request headers, never returned.

The answer carries `secret` once: keep it to verify the `Webmetic-Signature` header.
Up to 50 endpoints per account via the API (10 via the dashboard).

### Anfrage

`application/json`

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `url` | string | ja | https URL that receives the events (POST) |
| `events` | string[] | ja | Event types to receive: company.identified, company.returned, company.intensive_visit, segment.entered |
| `websites` | string[] \| null | nein | Websites of your account to receive events for; all of them when omitted |
| `description` | string | nein | Shown in the dashboard, for example 'Clay table Leads' |
| `segment_id` | string \| null | nein | Segment id for segment.entered (the segment's website must be among the websites) |
| `headers` | Header[] | nein | Up to 3 custom request headers |
| `headers[].name` | string | ja | Header name, for example X-Api-Key |
| `headers[].value` | string | ja | Header value |
| `source` | string | nein | Which tool receives the events: clay, n8n, make, zapier, custom |
| `created_via` | string | nein | Internal: 'dashboard' or 'api' (limits differ) |

### Antworten

| Status | Beschreibung |
| --- | --- |
| 201 | The endpoint with its signing secret |
| 400 | INVALID_URL, PRIVATE_ADDRESS, UNRESOLVABLE_HOST, SEGMENT_REQUIRED, SEGMENT_WEBSITE |
| 403 | API_KEY_MISSING, API_KEY_INVALID, API_KEY_NOT_FOUND, WEBSITE_NOT_AUTHORIZED |
| 404 | WEBHOOK_NOT_FOUND, SEGMENT_NOT_FOUND |
| 409 | WEBHOOK_LIMIT_REACHED |
| 422 | Validation Error |

Felder der Antwort 201:

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | ja |  |
| `url` | string | ja |  |
| `description` | string | nein |  |
| `events` | string[] | ja |  |
| `websites` | string[] | ja |  |
| `segment_id` | string \| null | nein |  |
| `segment_label` | string \| null | nein |  |
| `header_names` | string[] | nein |  |
| `source` | string | nein |  |
| `status` | string | ja |  |
| `created_via` | string | nein |  |
| `created_at` | string | ja |  |
| `updated_at` | string | ja |  |
| `last_success_at` | string \| null | nein |  |
| `last_failure_at` | string \| null | nein |  |
| `failing_since` | string \| null | nein |  |
| `disabled_at` | string \| null | nein |  |
| `disabled_reason` | string \| null | nein |  |
| `secret_rotated_at` | string \| null | nein |  |
| `secret` | string | ja | HMAC secret for the Webmetic-Signature header; shown once |

### Beispiel

```bash
curl -X POST 'https://hub.webmetic.de/webhooks' \
  -H 'Authorization: wmtc_IHR_API_SCHLUESSEL' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://website.example/webhook","events":["company.identified"]}'
```