Webhooks API - Dokumentacja

API Webhooks pozwala tworzyć, zarządzać i testować endpointy webhooków dla powiadomień w czasie rzeczywistym.

Utwórz webhook

Zarejestruj nowy endpoint webhooka.

POST /v1/webhooks

Body żądania

Pole	Typ	Wymagane	Opis
`name`	string	Tak	Nazwa webhooka
`url`	string	Tak	URL endpointu HTTPS
`events`	array	Tak	Typy zdarzeń do otrzymywania
`description`	string	Nie	Czytelny opis
`secret`	string	Nie	Własny sekret podpisu (auto-generowany jeśli pominięty)

Dostępne zdarzenia

Zdarzenie	Opis
`message.delivered`	Email zaakceptowany przez serwer odbiorcy
`message.bounced`	Email odrzucony
`message.deferred`	Tymczasowy błąd, ponowimy próbę
`message.opened`	Odbiorca otworzył email
`message.clicked`	Odbiorca kliknął link
`message.unsubscribed`	Odbiorca się wypisał
`message.complained`	Oznaczono jako spam
`quality.alert`	Alert jakości wysyłki

Email przychodzący (inbound.received) jest dostarczany przez akcję webhook na regule przychodzącej, nie przez ten endpoint subskrypcji — ma odrębny, płaski format payloadu. Zobacz przewodnik Webhooks po szczegóły.

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://twojaapka.pl/webhooks/mailingapi",
    "events": ["message.delivered", "message.bounced", "message.complained", "message.opened", "message.clicked"],
    "description": "Produkcyjny webhook"
  }'

Odpowiedź

{
  "id": "wh_abc123",
  "name": "Production webhook",
  "url": "https://twojaapka.pl/webhooks/mailingapi",
  "events": ["message.delivered", "message.bounced", "message.complained", "message.opened", "message.clicked"],
  "description": "Produkcyjny webhook",
  "secret": "whsec_1a2b3c4d5e6f...",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z"
}

Ważne: Zapisz secret — będzie potrzebny do weryfikacji podpisów webhooków.

Lista webhooków

Pobierz wszystkie webhooki dla Twojego konta.

GET /v1/webhooks

Przykładowe żądanie

curl https://api.mailingapi.com/v1/webhooks \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://twojaapka.pl/webhooks/mailingapi",
      "events": ["message.delivered", "message.bounced"],
      "status": "active",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Pobierz webhook

Pobierz szczegóły konkretnego webhooka.

GET /v1/webhooks/{webhook_id}

Przykładowe żądanie

curl https://api.mailingapi.com/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "id": "wh_abc123",
  "url": "https://twojaapka.pl/webhooks/mailingapi",
  "events": ["message.delivered", "message.bounced", "message.complained", "message.opened", "message.clicked"],
  "description": "Produkcyjny webhook",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z",
  "stats": {
    "total_sent": 15420,
    "successful": 15380,
    "failed": 40,
    "last_success": "2024-01-20T15:30:00Z",
    "last_failure": "2024-01-20T14:00:00Z"
  }
}

Statusy webhooka

Status	Opis
`active`	Webhook otrzymuje zdarzenia
`paused`	Tymczasowo wyłączony
`failing`	Wiele kolejnych błędów
`disabled`	Permanentnie wyłączony

Aktualizuj webhook

Zaktualizuj konfigurację webhooka.

PATCH /v1/webhooks/{webhook_id}

Body żądania

Pole	Typ	Opis
`url`	string	Nowy URL endpointu
`events`	array	Nowa lista zdarzeń
`description`	string	Nowy opis
`status`	string	`active` lub `paused`

Przykładowe żądanie

curl -X PATCH https://api.mailingapi.com/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["message.delivered", "message.bounced"],
    "status": "paused"
  }'

Odpowiedź

{
  "id": "wh_abc123",
  "url": "https://twojaapka.pl/webhooks/mailingapi",
  "events": ["message.delivered", "message.bounced"],
  "status": "paused",
  "updated_at": "2024-01-20T16:00:00Z"
}

Usuń webhook

Usuń endpoint webhooka.

DELETE /v1/webhooks/{webhook_id}

Przykładowe żądanie

curl -X DELETE https://api.mailingapi.com/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

204 No Content

Format payloadu webhooka

Wszystkie payloady webhooków mają tę strukturę:

{
  "id": "evt_1234567890",
  "type": "message.delivered",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "message_id": "msg_abc123",
    "from": "hello@twojadomena.pl",
    "to": "user@example.com",
    "subject": "Twoje zamówienie wysłane",
    "metadata": {
      "user_id": "usr_123"
    }
  }
}

Pole id jest generowane raz na zdarzenie i nie zmienia się między próbami doręczenia — używaj go jako klucza idempotencji. Do rozróżniania ponowień służy nagłówek X-MailingAPI-Delivery-Attempt.

Weryfikacja podpisu

Weryfikuj autentyczność webhooka używając nagłówka X-MailingAPI-Signature:

X-MailingAPI-Signature: t=1705315800,v1=5d2a...

Zobacz przewodnik Webhooks po przykłady implementacji.

Kody błędów

Kod	Opis
`invalid_url`	URL musi być HTTPS
`invalid_events`	Nieznany typ zdarzenia
`webhook_not_found`	ID webhooka nie znalezione
`webhook_disabled`	Webhook został wyłączony