Webhooky

Registrujte endpointy, které přijímají podepsaná oznámení o událostech.

Základní URLhttps://api.emailit.com/v2Autentizace Chyby Limity rychlosti

POST/webhooks
GET/webhooks/{id}
POST/webhooks/{id}
GET/webhooks
DEL/webhooks/{id}
POST/webhooks/{id}/test
POST/webhooks/{id}/reset-secret
POST/webhooks/{id}/retry-failed
POST/webhooks/{id}/requests/{request_id}/retry

Vytvoření webhooku

Vytvoří endpoint webhooku ve vašem workspace. Emailit na URL posílá odpovídající události v dávkách po nejvýše 100 jako pole JSON podepsané tajným klíčem webhooku secret. Formát požadavku popisuje stránka Požadavky webhooků. Vyžaduje API klíč s oprávněním full.

POST/webhooks

Tělo požadavku

namestringPovinné

Název webhooku. Musí být ve workspace jedinečný; v ostatních endpointech pro webhooky ho můžete použít místo ID.

urlstringPovinné

Endpoint, který přijímá události. Přijímají se URL s http i https; v produkci používejte https.

Emailit při uložení přeloží název hostitele a odmítne localhost, privátní, link-local a další rezervované IP adresy. Při doručování se přesměrování nesledují, takže použijte konečné URL.

all_eventsboolean

Posílat všechny typy událostí, včetně typů přidaných později. Výchozí hodnota je false. Při true se events ignoruje.

enabledboolean

Jestli Emailit webhooku doručuje události. Výchozí hodnota je true.

eventsstring[]

Typy událostí, které se mají posílat, například ["email.delivered", "email.bounced"]. Viz Typy událostí. Výchozí hodnota je [], což spolu s all_events: false znamená, že webhook nedostane nic.

Názvy událostí se nevalidují. Typ s překlepem se uloží, ale nikdy neodpovídá žádné události.

filterobject | null

Filtr obsahu. Emailit posílá jen události, jejichž objekt odpovídá pravidlům. Dostupné v tarifech Pro, Business a Custom; filtr s pravidly vrací v tarifu Pay as you go 403.

filter.matchstring

all (výchozí) pošle událost, když odpovídají všechna pravidla. any ji pošle, když odpovídá alespoň jedno pravidlo.

filter.rulesobject[]

Nejvýše 25 pravidel.

filter.rules[].fieldstringPovinné

Cesta k poli objektu události zapsaná s tečkami, například to, status, meta.plan nebo u událostí prokliku a otevření email.campaign.id. Úvodní payload. se ignoruje.

filter.rules[].operatorstringPovinné

equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, is_set, is_not_set, in nebo not_in. Textové operátory porovnávají hodnoty jako řetězce; greater_than a less_than porovnávají čísla.

filter.rules[].valueany

Hodnota k porovnání. Povinná u všech operátorů kromě is_set a is_not_set. U in a not_in použijte pole.

Odpověď

Vrací 201 Created s objektem webhooku včetně tajného klíče secret (whsec_ a za ním 64 hexadecimálních znaků). Tajným klíčem ověřujte podpisy požadavků. Znovu ho načtete endpointem Načtení webhooku a vyměníte endpointem Výměna tajného klíče.

Stavový kód	Kdy
`400`	Chybí `name` nebo `url`, URL je neplatné, nelze ho přeložit nebo odkazuje na blokovanou adresu, nebo je neplatný filtr.
`403`	Filtr má pravidla a váš tarif filtry webhooků nezahrnuje. Tělo je `{"error": "plan_required", "required_plan": "pro"}`.
`409`	Webhook s tímto názvem už existuje. Tělo obsahuje pole `existing` s `id` a `name` existujícího webhooku.
`422`	Workspace dosáhl limitu webhooků svého tarifu. Tělo obsahuje `usage.used` a `usage.limit`. Viz Limity a kvóty.

POST/webhooks

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const webhook = await emailit.webhooks.create({
    name: 'Production events',
    url: 'https://api.acme.com/webhooks/emailit',
    events: ['email.delivered']
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

webhook = client.webhooks.create({
    "name": "Production events",
    "url": "https://api.acme.com/webhooks/emailit",
    "events": ["email.delivered"]
})

PHP

$emailit = Emailit::client('your_api_key');

$webhook = $emailit->webhooks()->create([
    'name' => 'Production events',
    'url' => 'https://api.acme.com/webhooks/emailit',
    'events' => ['email.delivered']
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

webhook = client.webhooks.create(
    name: "Production events",
    url: "https://api.acme.com/webhooks/emailit",
    events: ["email.delivered"]
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

webhook, err := client.Webhooks.Create(&emailit.CreateWebhookRequest{
    Name:   "Production events",
    Url:    "https://api.acme.com/webhooks/emailit",
    Events: []string{"email.delivered"},
})

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let webhook = emailit.webhooks.create(
    emailit::types::CreateWebhookParams::new(
        "Production events",
        "https://api.acme.com/webhooks/emailit"
    ).with_events(vec!["email.delivered".into()])
).await?;

Java

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject webhook = emailit.webhooks().create(
    WebhookCreateParams.builder()
        .setName("Production events")
        .setUrl("https://api.acme.com/webhooks/emailit")
        .setEvents(Arrays.asList("email.delivered"))
        .build()
);

using Emailit;
var emailit = new EmailitClient("your_api_key");

var webhook = emailit.Webhooks.Create(new WebhookCreateOptions {
    Name = "Production events",
    Url = "https://api.acme.com/webhooks/emailit",
    Events = new[] { "email.delivered" }
});

PHP

use Emailit\Laravel\Facades\Emailit;

$webhook = Emailit::webhooks()->create([
    'name' => 'Production events',
    'url' => 'https://api.acme.com/webhooks/emailit',
    'events' => ['email.delivered']
]);

Terminal

curl -X POST https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://api.acme.com/webhooks/emailit",
    "events": ["email.delivered"]
  }'

JSON

{
  "object": "webhook",
  "id": "wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e",
  "name": "Production events",
  "url": "https://api.acme.com/webhooks/emailit",
  "all_events": false,
  "enabled": true,
  "events": ["email.delivered", "email.bounced"],
  "filter": null,
  "filters_allowed": true,
  "last_used_at": null,
  "created_at": "2026-10-01T09:41:05.302000+00:00",
  "updated_at": "2026-10-01T09:41:05.302000+00:00",
  "secret": "whsec_175a02aca3fb7dc3107ca21e4224a73d058cacc628356a39e020422aec3ca434"
}

JSON

{
  "error": "URL resolves to a private/reserved IP address"
}

JSON

{
  "error": "plan_required",
  "required_plan": "pro"
}

JSON

{
  "error": "Webhook with this name already exists",
  "existing": {
    "object": "webhook",
    "id": "wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e",
    "name": "Production events"
  }
}

JSON

{
  "error": "Pay as you go includes 3 webhook endpoints.",
  "usage": {
    "used": 3,
    "limit": 3
  }
}

JSON

{
  "name": "Enterprise bounces",
  "url": "https://api.acme.com/webhooks/emailit",
  "events": ["email.bounced", "email.complained"],
  "filter": {
    "match": "all",
    "rules": [
      { "field": "meta.plan", "operator": "equals", "value": "enterprise" },
      { "field": "to", "operator": "not_contains", "value": "@acme.com" }
    ]
  }
}

Načtení webhooku

Vrací jeden webhook dohledaný podle ID, nebo podle názvu. Je to jediný čtecí endpoint, který vrací tajný klíč secret. Vyžaduje API klíč s oprávněním full.

GET/webhooks/:id

Parametry v cestě

idstringPovinné

ID webhooku (wh_…), nebo název webhooku zakódovaný pro URL.

Odpověď

Vrací 200 OK s objektem webhooku včetně secret a filters_allowed (jestli váš tarif webhooku povoluje filtr obsahu). last_used_at je čas posledního úspěšného doručení, nebo null, pokud se zatím nic nedoručilo.

Pokud žádný webhook neodpovídá, vrací 404 s error: "Webhook not found".

GET/webhooks/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const webhook = await emailit.webhooks.get('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

webhook = client.webhooks.get("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e")

PHP

$emailit = Emailit::client('your_api_key');

$webhook = $emailit->webhooks()->get('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

webhook = client.webhooks.get("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

webhook, err := client.Webhooks.Get("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e")

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let webhook = emailit.webhooks.get("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e").await?;

Java

import com.emailit.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject webhook = emailit.webhooks().get("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e");

using Emailit;
var emailit = new EmailitClient("your_api_key");

var webhook = emailit.Webhooks.Get("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e");

PHP

use Emailit\Laravel\Facades\Emailit;

$webhook = Emailit::webhooks()->get('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e');

Terminal

curl https://api.emailit.com/v2/webhooks/wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "object": "webhook",
  "id": "wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e",
  "name": "Production events",
  "url": "https://api.acme.com/webhooks/emailit",
  "all_events": false,
  "enabled": true,
  "events": ["email.delivered", "email.bounced"],
  "filter": {
    "match": "all",
    "rules": [
      { "field": "meta.plan", "operator": "equals", "value": "enterprise" }
    ]
  },
  "filters_allowed": true,
  "last_used_at": "2026-10-01T10:02:17.845000+00:00",
  "created_at": "2026-10-01T09:41:05.302000+00:00",
  "updated_at": "2026-10-01T09:41:05.302000+00:00",
  "secret": "whsec_175a02aca3fb7dc3107ca21e4224a73d058cacc628356a39e020422aec3ca434"
}

JSON

{
  "error": "Webhook not found"
}

Úprava webhooku

Upraví webhook. Pošlete jen pole, která chcete změnit; alespoň jedno je povinné. Tajný klíč se nemění; vyměníte ho endpointem Výměna tajného klíče. Vyžaduje API klíč s oprávněním full.

POST/webhooks/:id

Parametry v cestě

idstringPovinné

ID webhooku (wh_…), nebo název webhooku zakódovaný pro URL.

Tělo požadavku

namestring

Nový název. Musí být ve workspace jedinečný.

urlstring

Nové URL endpointu, http, nebo https. Validuje se stejně jako při vytvoření.

all_eventsboolean

true posílá všechny typy událostí a vymaže seznam events. Pokud nastavíte false, pošlete také events, jinak webhook nedostane nic.

enabledboolean

false doručování zastaví a true ho obnoví. Události, které nastanou, když je webhook vypnutý, se pro něj nezařadí do fronty a později se neodešlou.

eventsstring[]

Nahradí seznam typů událostí. Ignoruje se, dokud je all_events true. Názvy se nevalidují.

filterobject | null

Nahradí filtr obsahu, ve stejném formátu jako při vytvoření. Pokud ho chcete odebrat, pošlete null. Filtr s pravidly vyžaduje tarif Pro, Business nebo Custom.

Odpověď

Vrací 200 OK s upraveným webhookem. Neobsahuje secret; ten načtete endpointem Načtení webhooku.

Stavový kód	Kdy
`400`	Tělo neobsahuje žádné z výše uvedených polí, nebo je neplatné URL či filtr.
`403`	Filtr má pravidla a váš tarif filtry webhooků nezahrnuje (`plan_required`).
`404`	Parametru `id` neodpovídá žádný webhook.
`409`	Nový název už používá jiný webhook.

POST/webhooks/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const webhook = await emailit.webhooks.update('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e', {
    enabled: false
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

webhook = client.webhooks.update("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e", {
    "enabled": False
})

PHP

$emailit = Emailit::client('your_api_key');

$webhook = $emailit->webhooks()->update('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e', [
    'enabled' => false
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

webhook = client.webhooks.update("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e", enabled: false)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

webhook, err := client.Webhooks.Update("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e", &emailit.UpdateWebhookRequest{
    Enabled: false,
})

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let webhook = emailit.webhooks.update("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e",
    emailit::types::UpdateWebhookParams {
        enabled: Some(false),
        ..Default::default()
    }
).await?;

Java

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject webhook = emailit.webhooks().update("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e",
    WebhookUpdateParams.builder()
        .setEnabled(false)
        .build()
);

using Emailit;
var emailit = new EmailitClient("your_api_key");

var webhook = emailit.Webhooks.Update("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e", new WebhookUpdateOptions {
    Enabled = false
});

PHP

use Emailit\Laravel\Facades\Emailit;

$webhook = Emailit::webhooks()->update('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e', [
    'enabled' => false
]);

Terminal

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

JSON

{
  "object": "webhook",
  "id": "wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e",
  "name": "Production events",
  "url": "https://api.acme.com/webhooks/emailit",
  "all_events": false,
  "enabled": false,
  "events": ["email.delivered", "email.bounced"],
  "filter": null,
  "filters_allowed": true,
  "last_used_at": "2026-10-01T10:02:17.845000+00:00",
  "created_at": "2026-10-01T09:41:05.302000+00:00",
  "updated_at": "2026-10-01T10:15:40.000000+00:00"
}

JSON

{
  "error": "No valid fields provided for update. Provide at least one of: name, url, all_events, enabled, events, filter"
}

JSON

{
  "error": "Webhook not found"
}

JSON

{
  "error": "Another webhook with this name already exists"
}

Výpis webhooků

Vrací webhooky ve vašem workspace od nejnovějších a počet webhooků, který váš tarif povoluje. Tajné klíče seznam neobsahuje. Vyžaduje API klíč s oprávněním full.

GET/webhooks

Parametry dotazu

pageinteger

Číslo stránky, začíná na 1. Výchozí hodnota je 1.

limitinteger

Počet webhooků na stránce, od 1 do 100. Výchozí hodnota je 10.

searchstring

Hledá v názvu nebo URL webhooku bez ohledu na velikost písmen.

matchstring

Hodnota all (výchozí) vyžaduje shodu se všemi filtry. S hodnotou or stačí shoda s kterýmkoli filtrem. Viz Filtrování.

orderstring

Klíč řazení pro tento výpis. Viz klíče řazení níže.

directionstring

asc, nebo desc.

Filtry a řazení

Filtry výpisů jsou jedna úroveň parametrů dotazu ve tvaru key.condition=value. Parametry match, order a direction a seznam podmínek pro každý typ najdete na stránce Filtrování.

Klíče filtrů

Klíč	Typ	Podmínky
`name`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`url`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`enabled`	boolean	exact, not_exact
`created_at`	date	exact, before, after, empty, not_empty

Klíče řazení

V parametru order předejte jeden z těchto klíčů a v parametru direction hodnotu asc, nebo desc: name, url, enabled, created_at

Odpověď

Vrací 200 OK s webhooky v poli data, next_page_url a previous_page_url (na začátku a na konci seznamu null) a objekt usage: used je počet webhooků ve workspace, limit je maximum vašeho tarifu a filters_allowed udává, jestli váš tarif zahrnuje filtry obsahu.

GET/webhooks

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const webhooks = await emailit.webhooks.list();

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

webhooks = client.webhooks.list()

PHP

$emailit = Emailit::client('your_api_key');

$webhooks = $emailit->webhooks()->list();

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

webhooks = client.webhooks.list

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

webhooks, err := client.Webhooks.List(nil)

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let webhooks = emailit.webhooks.list(None).await?;

Java

import com.emailit.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject webhooks = emailit.webhooks().list();

using Emailit;
var emailit = new EmailitClient("your_api_key");

var webhooks = emailit.Webhooks.List();

PHP

use Emailit\Laravel\Facades\Emailit;

$webhooks = Emailit::webhooks()->list();

Terminal

curl https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "data": [
    {
      "object": "webhook",
      "id": "wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e",
      "name": "Production events",
      "url": "https://api.acme.com/webhooks/emailit",
      "all_events": false,
      "enabled": true,
      "events": ["email.delivered", "email.bounced"],
      "filter": null,
      "filters_allowed": true,
      "last_used_at": "2026-10-01T10:02:17.845000+00:00",
      "created_at": "2026-10-01T09:41:05.302000+00:00",
      "updated_at": "2026-10-01T10:02:17.845000+00:00"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null,
  "usage": {
    "used": 1,
    "limit": 10,
    "filters_allowed": true
  }
}

JSON

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Smazání webhooku

Trvale smaže webhook a jeho odběry událostí. Pokud chcete doručování zastavit jen dočasně, místo toho upravte webhook a nastavte enabled: false. Vyžaduje API klíč s oprávněním full.

DELETE/webhooks/:id

Parametry v cestě

idstringPovinné

ID webhooku (wh_…), nebo název webhooku zakódovaný pro URL.

Odpověď

Vrací 200 OK s id a name smazaného webhooku a deleted: true. Pokud žádný webhook neodpovídá, vrací 404 s error: "Webhook not found".

DELETE/webhooks/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.webhooks.delete('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.webhooks.delete("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e")

PHP

$emailit = Emailit::client('your_api_key');

$emailit->webhooks()->delete('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.webhooks.delete("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Webhooks.Delete("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e")

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

emailit.webhooks.delete("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e").await?;

Java

import com.emailit.*;
EmailitClient emailit = new EmailitClient("your_api_key");

emailit.webhooks().delete("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e");

using Emailit;
var emailit = new EmailitClient("your_api_key");

emailit.Webhooks.Delete("wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e");

PHP

use Emailit\Laravel\Facades\Emailit;

Emailit::webhooks()->delete('wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e');

Terminal

curl -X DELETE https://api.emailit.com/v2/webhooks/wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "object": "webhook",
  "id": "wh_2xLb3Kp9Qr1Vt7Mn5Ws0Yd4Hc8e",
  "name": "Production events",
  "deleted": true
}

JSON

{
  "error": "Webhook not found"
}

Odeslání testovací události

Pošle na URL webhooku ukázkovou událost zvoleného typu a vrátí odpověď vašeho endpointu. Použijte ho ke kontrole, že je váš endpoint dosažitelný a správně ověřuje podpisy. Vyžaduje API klíč s oprávněním full.

Požadavek má stejný formát, hlavičky a podpis jako skutečné doručení: pole JSON s jednou událostí, jejíž event_id začíná na evt_test_, podepsané aktuálním tajným klíčem webhooku. Odešle se, i když je webhook vypnutý nebo daný typ neodebírá, neukládá se jako požadavek webhooku a neopakuje se. Ukázková data jsou pevně daná a neodkazují na skutečné objekty.

Z jedné IP adresy můžete poslat 5 testovacích událostí za minutu; další vracejí 429.

POST/webhooks/{id}/test

Parametry v cestě

idstringpovinné

ID webhooku (wh_…), nebo název webhooku.

Parametry v těle požadavku

typestringpovinné

Typ události, který se má odeslat. Jeden z typů níže.

Zdroj	Typy událostí
E-mail	`email.accepted`, `email.scheduled`, `email.delivered`, `email.bounced`, `email.attempted`, `email.failed`, `email.rejected`, `email.clicked`, `email.loaded`, `email.complained`, `email.received`, `email.suppressed`, `email.canceled`, `email.unsubscribed`, `email.resubscribed`
Doména	`domain.created`, `domain.updated`, `domain.deleted`
Seznam kontaktů	`audience.created`, `audience.updated`, `audience.deleted`
Odběratel	`subscriber.created`, `subscriber.updated`, `subscriber.deleted`
Kontakt	`contact.created`, `contact.updated`, `contact.deleted`
Šablona	`template.created`, `template.updated`, `template.deleted`
Blokace	`suppression.created`, `suppression.updated`, `suppression.deleted`
Ověření e-mailu	`email_verification.created`, `email_verification.updated`, `email_verification_list.created`, `email_verification_list.updated`
Kampaň	`campaign.created`, `campaign.updated`, `campaign.deleted`, `campaign.scheduled`, `campaign.queued`, `campaign.sending`, `campaign.testing`, `campaign.sent`, `campaign.canceled`, `campaign.archived`

Význam jednotlivých událostí najdete na stránce Typy událostí.

Odpověď

okboolean

true, pokud váš endpoint odpověděl stavovým kódem 2xx.

status_codeinteger

Stavový kód HTTP vašeho endpointu. 0, pokud se Emailit nemohl připojit, požadavku po 30 sekundách vypršel časový limit, endpoint přesměroval (přesměrování se nesledují) nebo URL odkazuje na blokovanou adresu.

bodystring

Prvních 2 000 znaků odpovědi vašeho endpointu, nebo chyba připojení.

typestring

Odeslaný typ události.

payloadobject[]

Přesné pole JSON, které se odeslalo.

Pokud type chybí nebo je neznámý, vrací 400, pokud webhook neexistuje, vrací 404, a když překročíte limit pro testy, vrací 429.

POST/webhooks/{id}/test

Terminal

curl -X POST https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/test \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "email.delivered" }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ type: 'email.delivered' }),
});
const { ok, status_code, body } = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/test",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"type": "email.delivered"},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/test', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['type' => 'email.delivered'],
]);
$result = json_decode($response->getBody(), true);

JSON

{
  "ok": true,
  "status_code": 200,
  "type": "email.delivered",
  "payload": [
    {
      "event_id": "evt_test_3G0pUekgBm1uIxi9m4C380H70Zq",
      "type": "email.delivered",
      "object": {
        "id": "eml_test_001",
        "email_id": 12345,
        "message_id": "<test-token@mydomain.com>",
        "from": "sender@mydomain.com",
        "to": "recipient@example.com",
        "subject": "Test email",
        "status": "delivered",
        "delivered_at": "2026-01-15T10:30:00.000Z"
      },
      "data": {
        "object": {
          "id": "eml_test_001",
          "email_id": 12345,
          "message_id": "<test-token@mydomain.com>",
          "from": "sender@mydomain.com",
          "to": "recipient@example.com",
          "subject": "Test email",
          "status": "delivered",
          "delivered_at": "2026-01-15T10:30:00.000Z"
        }
      }
    }
  ],
  "body": "{\"received\":true}"
}

JSON

{
  "error": "Unknown event type"
}

JSON

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 1 minute"
}

Výměna tajného klíče

Vygeneruje pro webhook nový tajný klíč a vrátí ho. Vyžaduje API klíč s oprávněním full.

Starý tajný klíč se přestane používat okamžitě: každý požadavek odeslaný po výměně, včetně opakování dřívějších událostí, je podepsaný novým tajným klíčem. Žádné přechodné období není, takže tajný klíč na svém endpointu aktualizujte hned po výměně, nebo během přechodu krátce přijímejte oba. Viz Ověření podpisu webhooků.

POST/webhooks/{id}/reset-secret

Parametry v cestě

idstringpovinné

ID webhooku (wh_…), nebo název webhooku.

Odpověď

Vrací objekt webhooku s novým secret (whsec_ a za ním 64 hexadecimálních znaků). Pokud webhook neexistuje, vrací 404.

POST/webhooks/{id}/reset-secret

Terminal

curl -X POST https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/reset-secret \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/reset-secret', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { secret } = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/reset-secret",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
secret = r.json()["secret"]

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/reset-secret', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$secret = json_decode($response->getBody(), true)['secret'];

JSON

{
  "object": "webhook",
  "id": "wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ",
  "name": "Order notifications",
  "url": "https://acme.com/webhooks/emailit",
  "all_events": false,
  "enabled": true,
  "events": ["email.delivered", "email.bounced", "email.complained"],
  "filter": null,
  "last_used_at": "2026-10-01T12:58:40.000000+00:00",
  "created_at": "2026-08-14T09:12:03.000000+00:00",
  "updated_at": "2026-10-01T13:20:11.000000+00:00",
  "secret": "whsec_a0a593d006bdec5aff2f21e88afd543ba239431acbe7d8dc7a9723d76e0a64e2"
}

JSON

{
  "error": "Webhook not found"
}

Opakování neúspěšných požadavků

Znovu zařadí k doručení všechny požadavky tohoto webhooku, které za posledních 7 dní trvale selhaly. Vyžaduje API klíč s oprávněním full.

Požadavek trvale selže po posledním automatickém opakování (11 pokusů během několika dní; viz Opakování a selhání). Znovu zařazené požadavky začínají od začátku s úplným plánem opakování a doručí se během několika sekund. Pokud se do fronty zařadí alespoň jeden požadavek a webhook byl vypnutý, například po 3 dnech nepřetržitých chyb, znovu se zapne.

Nejdřív opravte svůj endpoint, jinak požadavky selžou znovu. Pokud chcete zopakovat jen jeden požadavek, použijte endpoint Opakování jednoho požadavku.

POST/webhooks/{id}/retry-failed

Parametry v cestě

idstringpovinné

ID webhooku (wh_…), nebo název webhooku.

Odpověď

retriedinteger

Počet znovu zařazených požadavků. 0, pokud nebylo co opakovat; zapnutí nebo vypnutí webhooku se v tom případě nemění.

Pokud webhook neexistuje, vrací 404.

POST/webhooks/{id}/retry-failed

Terminal

curl -X POST https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/retry-failed \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/retry-failed', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { retried } = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/retry-failed",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
retried = r.json()["retried"]

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/retry-failed', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$retried = json_decode($response->getBody(), true)['retried'];

JSON

{
  "retried": 37
}

JSON

{
  "error": "Webhook not found"
}

Opakování jednoho požadavku

Znovu zařadí k doručení jeden trvale neúspěšný požadavek webhooku s novým plánem opakování. Pokud byl webhook vypnutý, znovu se zapne. Vyžaduje API klíč s oprávněním full.

Takto lze zopakovat jen požadavky, které vyčerpaly svá automatická opakování; požadavky, které ještě čekají nebo se opakují, vracejí 400. ID požadavků (whr_…) najdete na kartě Requests u webhooku v sekci Email APIWebhooks. Pokud chcete zopakovat vše za posledních 7 dní najednou, použijte endpoint Opakování neúspěšných požadavků.

POST/webhooks/{id}/requests/{request_id}/retry

Parametry v cestě

idstringpovinné

ID webhooku (wh_…), nebo název webhooku.

request_idstringpovinné

ID požadavku webhooku (whr_…).

Odpověď

retriedinteger

Vždy 1.

idstring

ID požadavku, který se zařadil do fronty.

Stavový kód	Kdy
`400`	Požadavek trvale neselhal, nebo nemá žádnou událost k opětovnému odeslání.
`404`	Webhook neexistuje, nebo mu požadavek nepatří.

POST/webhooks/{id}/requests/{request_id}/retry

Terminal

curl -X POST https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/requests/whr_3tWVVMd2eHv3R9B5DWTLtwwU05X/retry \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch(
  'https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/requests/whr_3tWVVMd2eHv3R9B5DWTLtwwU05X/retry',
  { method: 'POST', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } },
);
const result = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/requests/whr_3tWVVMd2eHv3R9B5DWTLtwwU05X/retry",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('webhooks/wh_3NGa6raJ3s1VJ75lO9km6Dqg4cQ/requests/whr_3tWVVMd2eHv3R9B5DWTLtwwU05X/retry', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);

JSON

{
  "retried": 1,
  "id": "whr_3tWVVMd2eHv3R9B5DWTLtwwU05X"
}

JSON

{
  "error": "Only permanently failed requests can be retried"
}

JSON

{
  "error": "Webhook request not found"
}