Webhooks

Endpunkte registrieren, die signierte Event-Benachrichtigungen empfangen.

Basis-URLhttps://api.emailit.com/v2Authentifizierung Fehler Rate Limits

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

Webhook erstellen

Erstellt einen Webhook-Endpunkt in Ihrem Workspace. Emailit sendet passende Events in Batches von bis zu 100 an die URL, als JSON-Array, das mit dem secret des Webhooks signiert ist. Das Anfrageformat finden Sie unter Webhook-Anfragen. Erfordert einen API-Schlüssel mit dem Scope full.

POST/webhooks

Anfrage-Body

namestringErforderlich

Name des Webhooks. Muss im Workspace eindeutig sein; Sie können ihn in den anderen API-Endpunkten für Webhooks statt der ID verwenden.

urlstringErforderlich

Endpunkt, der die Events empfängt. http- und https-URLs werden akzeptiert; verwenden Sie im Produktivbetrieb https.

Emailit löst den Hostnamen beim Speichern auf und lehnt localhost, private, Link-Local- und andere reservierte IP-Adressen ab. Bei der Zustellung folgt Emailit keinen HTTP-Redirects; verwenden Sie also die endgültige URL.

all_eventsboolean

Alle Event-Typen senden, auch später hinzukommende. Standardwert: false. Bei true wird events ignoriert.

enabledboolean

Ob Emailit Events an den Webhook zustellt. Standardwert: true.

eventsstring[]

Zu sendende Event-Typen, zum Beispiel ["email.delivered", "email.bounced"]. Siehe Event-Typen. Standardwert: []; zusammen mit all_events: false empfängt der Webhook dann nichts.

Event-Namen werden nicht validiert. Ein falsch geschriebener Typ wird gespeichert, passt aber nie zu einem Event.

filterobject | null

Payload-Filter. Emailit sendet nur Events, deren Objekt den Regeln entspricht. Verfügbar in den Tarifen Pro, Business und Custom; ein Filter mit Regeln gibt bei Pay as you go 403 zurück.

filter.matchstring

all (Standardwert) sendet ein Event, wenn alle Regeln zutreffen. any sendet es, wenn mindestens eine Regel zutrifft.

filter.rulesobject[]

Bis zu 25 Regeln.

filter.rules[].fieldstringErforderlich

Pfad in Punktnotation innerhalb des Event-Objekts, zum Beispiel to, status, meta.plan oder bei Klick- und Öffnungs-Events email.campaign.id. Ein vorangestelltes payload. wird ignoriert.

filter.rules[].operatorstringErforderlich

equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, is_set, is_not_set, in oder not_in. Textoperatoren vergleichen Werte als Strings; greater_than und less_than vergleichen Zahlen.

filter.rules[].valueany

Vergleichswert. Erforderlich für alle Operatoren außer is_set und is_not_set. Verwenden Sie bei in und not_in ein Array.

Rückgabe

Gibt 201 Created mit dem Webhook-Objekt zurück, einschließlich des Signatur-Secrets secret (whsec_ gefolgt von 64 Hexadezimalzeichen). Mit dem Secret verifizieren Sie die Signaturen der Anfragen. Sie können es mit Webhook abrufen erneut auslesen und mit Signatur-Secret rotieren rotieren.

Status	Wann
`400`	`name` oder `url` fehlt, die URL ist ungültig, lässt sich nicht auflösen oder zeigt auf eine blockierte Adresse, oder der Filter ist ungültig.
`403`	Der Filter hat Regeln und Ihr Tarif enthält keine Webhook-Filter. Der Body lautet `{"error": "plan_required", "required_plan": "pro"}`.
`409`	Ein Webhook mit diesem Namen existiert bereits. Der Body enthält in `existing` die `id` und den `name` des vorhandenen Webhooks.
`422`	Der Workspace hat das Webhook-Limit seines Tarifs erreicht. Der Body enthält `usage.used` und `usage.limit`. Siehe Limits.

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" }
    ]
  }
}

Webhook abrufen

Gibt einen Webhook zurück, gesucht per ID oder Name. Das ist der einzige lesende Endpunkt, der das Signatur-Secret secret zurückgibt. Erfordert einen API-Schlüssel mit dem Scope full.

GET/webhooks/:id

Pfadparameter

idstringErforderlich

ID des Webhooks (wh_…) oder sein Name, URL-kodiert.

Rückgabe

Gibt 200 OK mit dem Webhook-Objekt zurück, einschließlich secret und filters_allowed (ob Ihr Tarif dem Webhook einen Payload-Filter erlaubt). last_used_at ist der Zeitpunkt der letzten erfolgreichen Zustellung oder null, wenn noch nichts zugestellt wurde.

Gibt 404 mit error: "Webhook not found" zurück, wenn kein Webhook passt.

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"
}

Webhook aktualisieren

Aktualisiert einen Webhook. Senden Sie nur die Felder, die Sie ändern möchten; mindestens eines ist erforderlich. Das Signatur-Secret ändert sich nicht; Sie rotieren es mit Signatur-Secret rotieren. Erfordert einen API-Schlüssel mit dem Scope full.

POST/webhooks/:id

Pfadparameter

idstringErforderlich

ID des Webhooks (wh_…) oder sein Name, URL-kodiert.

Anfrage-Body

namestring

Neuer Name. Muss im Workspace eindeutig sein.

urlstring

Neue URL des Endpunkts, http oder https. Wird genauso validiert wie beim Erstellen.

all_eventsboolean

true sendet alle Event-Typen und leert die Liste events. Wenn Sie den Wert auf false setzen, senden Sie auch events, sonst empfängt der Webhook nichts.

enabledboolean

false stoppt Zustellungen, true nimmt sie wieder auf. Events, die auftreten, während der Webhook deaktiviert ist, werden für ihn nicht in die Warteschlange gestellt und auch später nicht gesendet.

eventsstring[]

Ersetzt die Liste der Event-Typen. Wird ignoriert, solange all_events den Wert true hat. Namen werden nicht validiert.

filterobject | null

Ersetzt den Payload-Filter, im selben Format wie beim Erstellen. Senden Sie null, um ihn zu entfernen. Ein Filter mit Regeln setzt den Tarif Pro, Business oder Custom voraus.

Rückgabe

Gibt 200 OK mit dem aktualisierten Webhook zurück. Das secret ist nicht enthalten; lesen Sie es mit Webhook abrufen aus.

Status	Wann
`400`	Der Body enthält keines der obigen Felder oder URL bzw. Filter sind ungültig.
`403`	Der Filter hat Regeln und Ihr Tarif enthält keine Webhook-Filter (`plan_required`).
`404`	Kein Webhook passt zu `id`.
`409`	Ein anderer Webhook verwendet bereits den neuen Namen.

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"
}

Webhooks auflisten

Gibt die Webhooks in Ihrem Workspace zurück, die neuesten zuerst, und wie viele Ihr Tarif erlaubt. Signatur-Secrets sind in der Liste nicht enthalten. Erfordert einen API-Schlüssel mit dem Scope full.

GET/webhooks

Query-Parameter

pageinteger

Seitennummer, beginnend bei 1. Standardwert: 1.

limitinteger

Webhooks pro Seite, von 1 bis 100. Standardwert: 10.

searchstring

Abgleich mit Name oder URL des Webhooks, ohne Beachtung der Groß-/Kleinschreibung.

matchstring

all (Standardwert) verlangt, dass alle Filter zutreffen. or trifft zu, wenn ein beliebiger Filter passt. Siehe Filtern und Sortieren.

orderstring

Sortierschlüssel für diese Liste. Siehe die Sortierschlüssel unten.

directionstring

asc oder desc.

Filter und Sortierung

Listenfilter sind Query-Parameter der Form key.condition=value auf einer einzigen Ebene. match, order, direction und die Bedingungen pro Typ finden Sie unter Filtern und Sortieren.

Filterschlüssel

Schlüssel	Typ	Bedingungen
`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

Sortierschlüssel

Übergeben Sie in order einen dieser Schlüssel und in direction den Wert asc oder desc: name, url, enabled, created_at

Rückgabe

Gibt 200 OK mit den Webhooks in data, mit next_page_url und previous_page_url (null am jeweiligen Ende) sowie einem Objekt usage zurück: used ist die Anzahl der Webhooks im Workspace, limit das Maximum Ihres Tarifs und filters_allowed gibt an, ob Ihr Tarif Payload-Filter enthält.

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"
}

Webhook löschen

Löscht einen Webhook und seine Event-Abonnements endgültig. Um Zustellungen vorübergehend zu stoppen, aktualisieren Sie den Webhook stattdessen mit enabled: false. Erfordert einen API-Schlüssel mit dem Scope full.

DELETE/webhooks/:id

Pfadparameter

idstringErforderlich

ID des Webhooks (wh_…) oder sein Name, URL-kodiert.

Rückgabe

Gibt 200 OK mit id und name des gelöschten Webhooks sowie deleted: true zurück. Gibt 404 mit error: "Webhook not found" zurück, wenn kein Webhook passt.

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"
}

Test-Event senden

Sendet ein Beispiel-Event des gewählten Typs an die URL des Webhooks und gibt die Antwort Ihres Endpunkts zurück. So prüfen Sie, ob Ihr Endpunkt erreichbar ist und Signaturen korrekt verifiziert. Erfordert einen API-Schlüssel mit dem Scope full.

Die Anfrage hat dasselbe Format, dieselben Header und dieselbe Signatur wie eine echte Zustellung: ein JSON-Array mit einem Event, dessen event_id mit evt_test_ beginnt, signiert mit dem aktuellen Secret des Webhooks. Sie wird auch gesendet, wenn der Webhook deaktiviert ist oder diesen Typ nicht abonniert hat, wird nicht als Webhook-Anfrage gespeichert und nicht wiederholt. Die Beispieldaten sind fest vorgegeben und beziehen sich nicht auf echte Objekte.

Sie können 5 Test-Events pro Minute von derselben IP-Adresse senden; weitere geben 429 zurück.

POST/webhooks/{id}/test

Pfadparameter

idstringerforderlich

Die ID des Webhooks (wh_…) oder sein Name.

Body-Parameter

typestringerforderlich

Der zu sendende Event-Typ. Einer der Typen unten.

Ressource	Event-Typen
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`
Domain	`domain.created`, `domain.updated`, `domain.deleted`
Kontaktliste	`audience.created`, `audience.updated`, `audience.deleted`
Abonnent	`subscriber.created`, `subscriber.updated`, `subscriber.deleted`
Kontakt	`contact.created`, `contact.updated`, `contact.deleted`
Vorlage	`template.created`, `template.updated`, `template.deleted`
Sperrung	`suppression.created`, `suppression.updated`, `suppression.deleted`
E-Mail-Verifizierung	`email_verification.created`, `email_verification.updated`, `email_verification_list.created`, `email_verification_list.updated`
Kampagne	`campaign.created`, `campaign.updated`, `campaign.deleted`, `campaign.scheduled`, `campaign.queued`, `campaign.sending`, `campaign.testing`, `campaign.sent`, `campaign.canceled`, `campaign.archived`

Was jedes Event bedeutet, erfahren Sie unter Event-Typen.

Rückgabe

okboolean

true, wenn Ihr Endpunkt mit einem 2xx-Status geantwortet hat.

status_codeinteger

Der HTTP-Status Ihres Endpunkts. 0, wenn Emailit keine Verbindung herstellen konnte, die Anfrage nach 30 Sekunden in ein Timeout lief, der Endpunkt umgeleitet hat (HTTP-Redirects werden nicht verfolgt) oder die URL auf eine blockierte Adresse zeigt.

bodystring

Die ersten 2.000 Zeichen der Antwort Ihres Endpunkts oder der Verbindungsfehler.

typestring

Der gesendete Event-Typ.

payloadobject[]

Das exakte JSON-Array, das gesendet wurde.

Gibt 400 zurück, wenn type fehlt oder unbekannt ist, 404, wenn der Webhook nicht existiert, und 429, wenn Sie das Testlimit überschreiten.

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"
}

Signatur-Secret rotieren

Erzeugt ein neues Signatur-Secret für den Webhook und gibt es zurück. Erfordert einen API-Schlüssel mit dem Scope full.

Das alte Secret wird sofort nicht mehr verwendet: Jede nach der Rotation gesendete Anfrage, einschließlich Wiederholungen früherer Events, wird mit dem neuen Secret signiert. Es gibt keinen Übergangszeitraum; aktualisieren Sie das Secret in Ihrem Endpunkt also direkt nach der Rotation oder akzeptieren Sie während der Umstellung kurzzeitig beide Secrets. Siehe Webhook-Signaturen verifizieren.

POST/webhooks/{id}/reset-secret

Pfadparameter

idstringerforderlich

Die ID des Webhooks (wh_…) oder sein Name.

Rückgabe

Gibt das Webhook-Objekt mit dem neuen secret zurück (whsec_ gefolgt von 64 Hexadezimalzeichen). Gibt 404 zurück, wenn der Webhook nicht existiert.

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"
}

Fehlgeschlagene Anfragen wiederholen

Stellt jede Anfrage dieses Webhooks, die in den letzten 7 Tagen endgültig fehlgeschlagen ist, erneut zur Zustellung in die Warteschlange. Erfordert einen API-Schlüssel mit dem Scope full.

Eine Anfrage schlägt nach ihrer letzten automatischen Wiederholung endgültig fehl (11 Versuche über mehrere Tage; siehe Wiederholungen und Fehlschläge). Erneut gestellte Anfragen beginnen wieder mit dem vollständigen Wiederholungsplan und werden innerhalb von Sekunden zugestellt. Wird mindestens eine Anfrage in die Warteschlange gestellt und war der Webhook deaktiviert, etwa nach 3 Tagen durchgehender Fehlschläge, wird er wieder aktiviert.

Beheben Sie zuerst das Problem an Ihrem Endpunkt, sonst schlagen die Anfragen erneut fehl. Um eine einzelne Anfrage zu wiederholen, nutzen Sie Einzelne Anfrage wiederholen.

POST/webhooks/{id}/retry-failed

Pfadparameter

idstringerforderlich

Die ID des Webhooks (wh_…) oder sein Name.

Rückgabe

retriedinteger

Anzahl der erneut in die Warteschlange gestellten Anfragen. 0, wenn es nichts zu wiederholen gab; der Aktivierungsstatus des Webhooks ändert sich dann nicht.

Gibt 404 zurück, wenn der Webhook nicht existiert.

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"
}

Einzelne Anfrage wiederholen

Stellt eine endgültig fehlgeschlagene Webhook-Anfrage mit einem neuen Wiederholungsplan erneut zur Zustellung in die Warteschlange. War der Webhook deaktiviert, wird er wieder aktiviert. Erfordert einen API-Schlüssel mit dem Scope full.

Nur Anfragen, deren automatische Wiederholungen ausgeschöpft sind, lassen sich auf diese Weise wiederholen; für noch ausstehende oder gerade wiederholte Anfragen gibt der Endpunkt 400 zurück. Anfrage-IDs (whr_…) finden Sie im Tab Requests des Webhooks unter Email APIWebhooks. Um alle Anfragen der letzten 7 Tage auf einmal zu wiederholen, nutzen Sie Fehlgeschlagene Anfragen wiederholen.

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

Pfadparameter

idstringerforderlich

Die ID des Webhooks (wh_…) oder sein Name.

request_idstringerforderlich

Die ID der Webhook-Anfrage (whr_…).

Rückgabe

retriedinteger

Immer 1.

idstring

Die ID der Anfrage, die in die Warteschlange gestellt wurde.

Status	Wann
`400`	Die Anfrage ist nicht endgültig fehlgeschlagen oder hat kein Event, das erneut gesendet werden kann.
`404`	Der Webhook existiert nicht oder die Anfrage gehört nicht zu ihm.

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"
}