[Intum Pomoc](https://intum.pl/pomoc.md) / [API](https://intum.pl/pomoc/konto/api.md)

# [Webhooki konta](https://intum.pl/pomoc/konto/api/webhooki.md)

Tworzenie, aktualizacja, usuwanie i listowanie webhooków konta przez API. Webhook reaguje na
zdarzenie w module (utworzenie/edycja/usunięcie rekordu, akcje custom) i dostarcza je na
zewnętrzny URL, do konektora albo uruchamia flow.

**Autoryzacja:** `Authorization: Bearer TOKEN` - token musi mieć uprawnienie **webhooks**
**Content-Type:** `application/json; charset=utf-8`

## API Endpoints

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/account/webhooks.json` | Lista webhooków konta |
| GET | `/account/webhooks/:id.json` | Pojedynczy webhook |
| POST | `/account/webhooks.json` | Utworzenie webhooka |
| PATCH | `/account/webhooks/:id.json` | Aktualizacja webhooka |
| DELETE | `/account/webhooks/:id.json` | Usunięcie webhooka |

## Pola webhooka

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `source_type` | string | tak | Model źródłowy zdarzenia, np. `"Helpdesk::Ticket"`, `"Crm::Client"`, `"Fiskator::Document"`. Lista dostępnych: pole `source_type` w formatce `/account/webhooks/new` |
| `kind` | string | tak | Akcja/zdarzenie: `"create"`, `"update"`, `"destroy"` lub akcja custom modelu (lista zależy od `source_type`) |
| `target_kind` | string | nie | Sposób dostarczenia: `"url"` (domyślny - POST na zewnętrzny URL), `"connector"`, `"flow"` |
| `url` | string | dla `target_kind: url` | Zewnętrzny URL, na który poleci POST z payloadem rekordu (unikalny per zdarzenie) |
| `target_code` | string | dla `connector` / `flow` | Kod konektora (`Connect::Connector`) albo przepływu (`Connect::Flow`) |
| `api_token` | string | nie | Token dołączany do requestu POST (autoryzacja po stronie odbiorcy) |
| `active` | boolean | nie | Czy webhook jest aktywny (domyślnie `true`); nieaktywny nie wysyła zdarzeń |

Zasady:

- `url` musi być unikalny w ramach (konto, `kind`, `source_type`) - duplikat zwróci błąd walidacji
- przy `target_kind: connector`/`flow` pole `url` jest ignorowane (czyszczone), przy `url` - `target_code`
- payload POST to JSON rekordu (`as_json` lub `as_webhook_payload` modelu), wysyłany asynchronicznie

## Format requestu

### POST - webhook na zewnętrzny URL

```
POST /account/webhooks.json
Authorization: Bearer TOKEN
Content-Type: application/json; charset=utf-8
```

```json
{
  "webhook": {
    "source_type": "Helpdesk::Ticket",
    "kind": "create",
    "url": "https://example.com/hooks/ticket-created",
    "api_token": "sekret-odbiorcy",
    "active": true
  }
}
```

### POST - webhook uruchamiający flow

```json
{
  "webhook": {
    "source_type": "Crm::Client",
    "kind": "update",
    "target_kind": "flow",
    "target_code": "moj_flow",
    "active": true
  }
}
```

### PATCH - wyłączenie webhooka

```json
{
  "webhook": {
    "active": false
  }
}
```

### Błąd walidacji (422 Unprocessable Content)

```json
{
  "url": ["zostało już zajęte"]
}
```

Klucze to nazwy pól, wartości to tablice komunikatów błędów.

## Powiązane

- [common_api](https://app.intum.pl/noe/prompt/common_api.md) - wspólne zasady API (format, autoryzacja, odpowiedzi)
- [connector_flow_api](https://app.intum.pl/noe/prompt/connector_flow_api.md) - API przepływów (Connect::Flow), których kody podajesz w `target_code`
- [account_crons_api](https://intum.intum.pl/kb/intum-kb/konto/api/crony) - cykliczne akcje konta (uruchamianie flow wg harmonogramu zamiast po zdarzeniu)