Webhook

Registra endpoint che ricevono notifiche firmate degli eventi.

URL di basehttps://api.emailit.com/v2Autenticazione Errori Limiti di frequenza

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

Crea un webhook

Crea un endpoint webhook nel workspace. Emailit invia gli eventi corrispondenti all’URL in batch fino a 100, come array JSON firmato con il secret del webhook. Per il formato delle richieste, vedi Richieste webhook. Richiede una chiave API con il permesso full.

POST/webhooks

Corpo della richiesta

namestringObbligatorio

Nome del webhook. Deve essere univoco nel workspace; puoi usarlo al posto dell’ID negli altri endpoint dei webhook.

urlstringObbligatorio

Endpoint che riceve gli eventi. Sono accettati URL http e https; in produzione usa https.

Emailit risolve il nome host al salvataggio e rifiuta localhost, gli indirizzi IP privati, link-local e gli altri indirizzi riservati. Durante la consegna i reindirizzamenti non vengono seguiti, quindi usa l’URL finale.

all_eventsboolean

Invia tutti i tipi di evento, compresi quelli aggiunti in futuro. Il valore predefinito è false. Quando è true, events viene ignorato.

enabledboolean

Indica se Emailit consegna gli eventi al webhook. Il valore predefinito è true.

eventsstring[]

Tipi di evento da inviare, ad esempio ["email.delivered", "email.bounced"]. Vedi Tipi di evento. Il valore predefinito è [], che con all_events: false significa che il webhook non riceve nulla.

I nomi degli eventi non vengono convalidati. Un tipo scritto male viene salvato ma non corrisponde mai a nessun evento.

filterobject | null

Filtro sul payload. Emailit invia solo gli eventi il cui oggetto corrisponde alle regole. Disponibile nei piani Pro, Business e Custom; con Pay as you go un filtro con regole restituisce 403.

filter.matchstring

all (predefinito) invia un evento quando corrispondono tutte le regole. any lo invia quando corrisponde almeno una regola.

filter.rulesobject[]

Fino a 25 regole.

filter.rules[].fieldstringObbligatorio

Percorso con punti all’interno dell’oggetto dell’evento, ad esempio to, status, meta.plan o, per gli eventi di clic e apertura, email.campaign.id. Un prefisso payload. iniziale viene ignorato.

filter.rules[].operatorstringObbligatorio

equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, is_set, is_not_set, in o not_in. Gli operatori di testo confrontano i valori come stringhe; greater_than e less_than confrontano numeri.

filter.rules[].valueany

Valore con cui confrontare. Obbligatorio per tutti gli operatori tranne is_set e is_not_set. Con in e not_in usa un array.

Restituisce

Restituisce 201 Created con l’oggetto webhook, compreso il secret di firma (whsec_ seguito da 64 caratteri esadecimali). Usa il secret per verificare le firme delle richieste. Puoi leggerlo di nuovo con Recupera un webhook e ruotarlo con Ruota il secret di firma.

Stato	Quando
`400`	Manca `name` o `url`, l’URL non è valido, non può essere risolto o punta a un indirizzo bloccato, oppure il filtro non è valido.
`403`	Il filtro ha delle regole e il piano non include i filtri dei webhook. Il corpo è `{"error": "plan_required", "required_plan": "pro"}`.
`409`	Esiste già un webhook con questo nome. Il corpo include `id` e `name` del webhook esistente in `existing`.
`422`	Il workspace ha raggiunto il limite di webhook del piano. Il corpo include `usage.used` e `usage.limit`. Vedi Limiti e quote.

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

Recupera un webhook

Restituisce un webhook, cercato per ID o per nome. È l’unico endpoint di lettura che restituisce il secret di firma. Richiede una chiave API con il permesso full.

GET/webhooks/:id

Parametri di percorso

idstringObbligatorio

ID del webhook (wh_…) o nome del webhook, codificato per l’URL.

Restituisce

Restituisce 200 OK con l’oggetto webhook, compresi secret e filters_allowed (indica se il piano consente al webhook di usare un filtro sul payload). last_used_at è il momento dell’ultima consegna riuscita, oppure null se non è stato ancora consegnato nulla.

Restituisce 404 con error: "Webhook not found" se nessun webhook corrisponde.

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

Aggiorna un webhook

Aggiorna un webhook. Invia solo i campi che vuoi modificare; ne serve almeno uno. Il secret di firma non cambia; per ruotarlo usa Ruota il secret di firma. Richiede una chiave API con il permesso full.

POST/webhooks/:id

Parametri di percorso

idstringObbligatorio

ID del webhook (wh_…) o nome del webhook, codificato per l’URL.

Corpo della richiesta

namestring

Nuovo nome. Deve essere univoco nel workspace.

urlstring

Nuovo URL dell’endpoint, http o https. Viene convalidato come in creazione.

all_eventsboolean

true invia tutti i tipi di evento e svuota l’elenco events. Se lo imposti su false, invia anche events, altrimenti il webhook non riceve nulla.

enabledboolean

false interrompe le consegne e true le riprende. Gli eventi che si verificano mentre il webhook è disattivato non vengono messi in coda per il webhook e non vengono inviati in seguito.

eventsstring[]

Sostituisce l’elenco dei tipi di evento. Viene ignorato finché all_events è true. I nomi non vengono convalidati.

filterobject | null

Sostituisce il filtro sul payload, nello stesso formato usato in creazione. Invia null per rimuoverlo. Un filtro con regole richiede un piano Pro, Business o Custom.

Restituisce

Restituisce 200 OK con il webhook aggiornato. Il secret non è incluso; per leggerlo usa Recupera un webhook.

Stato	Quando
`400`	Il corpo non contiene nessuno dei campi indicati sopra, oppure l’URL o il filtro non sono validi.
`403`	Il filtro ha delle regole e il piano non include i filtri dei webhook (`plan_required`).
`404`	Nessun webhook corrisponde a `id`.
`409`	Un altro webhook usa già il nuovo nome.

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

Elenca i webhook

Restituisce i webhook del workspace, a partire dal più recente, e quanti ne consente il piano. I secret di firma non sono inclusi nell’elenco. Richiede una chiave API con il permesso full.

GET/webhooks

Parametri di query

pageinteger

Numero di pagina, a partire da 1. Il valore predefinito è 1.

limitinteger

Webhook per pagina, da 1 a 100. Il valore predefinito è 10.

searchstring

Corrispondenza sul nome o sull’URL del webhook, senza distinzione tra maiuscole e minuscole.

matchstring

all (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.

orderstring

Chiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.

directionstring

asc o desc.

Filtri e ordinamento

I filtri degli elenchi sono un unico livello di parametri di query key.condition=value. Vedi Filtri e ordinamento per match, order, direction e l’elenco delle condizioni per tipo.

Chiavi di filtro

Chiave	Tipo	Condizioni
`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

Chiavi di ordinamento

Passa in order una di queste chiavi e in direction il valore asc o desc: name, url, enabled, created_at

Restituisce

Restituisce 200 OK con i webhook in data, next_page_url e previous_page_url (null alle due estremità) e un oggetto usage: used è il numero di webhook nel workspace, limit è il massimo consentito dal piano e filters_allowed indica se il piano include i filtri sul payload.

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

Elimina un webhook

Elimina definitivamente un webhook e le sue iscrizioni agli eventi. Per sospendere temporaneamente le consegne, aggiorna il webhook con enabled: false. Richiede una chiave API con il permesso full.

DELETE/webhooks/:id

Parametri di percorso

idstringObbligatorio

ID del webhook (wh_…) o nome del webhook, codificato per l’URL.

Restituisce

Restituisce 200 OK con id e name del webhook eliminato e deleted: true. Restituisce 404 con error: "Webhook not found" se nessun webhook corrisponde.

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

Invia un evento di test

Invia un evento di esempio del tipo che scegli all’URL del webhook e restituisce la risposta del tuo endpoint. Usalo per controllare che l’endpoint sia raggiungibile e verifichi correttamente le firme. Richiede una chiave API con il permesso full.

La richiesta ha lo stesso formato, gli stessi header e la stessa firma di una consegna reale: un array JSON con un evento il cui event_id inizia con evt_test_, firmato con il secret attuale del webhook. Viene inviata anche se il webhook è disattivato o non è iscritto a quel tipo, non viene salvata come richiesta webhook e non viene ritentata. I dati di esempio sono fissi e non si riferiscono a oggetti reali.

Puoi inviare 5 eventi di test al minuto dallo stesso indirizzo IP; oltre questo limite viene restituito 429.

POST/webhooks/{id}/test

Parametri di percorso

idstringobbligatorio

L’ID del webhook (wh_…) o il nome del webhook.

Parametri del corpo

typestringobbligatorio

Il tipo di evento da inviare. Uno dei tipi qui sotto.

Risorsa	Tipi di evento
Email	`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`
Dominio	`domain.created`, `domain.updated`, `domain.deleted`
Lista	`audience.created`, `audience.updated`, `audience.deleted`
Iscritto	`subscriber.created`, `subscriber.updated`, `subscriber.deleted`
Contatto	`contact.created`, `contact.updated`, `contact.deleted`
Template	`template.created`, `template.updated`, `template.deleted`
Soppressione	`suppression.created`, `suppression.updated`, `suppression.deleted`
Verifica email	`email_verification.created`, `email_verification.updated`, `email_verification_list.created`, `email_verification_list.updated`
Campagna	`campaign.created`, `campaign.updated`, `campaign.deleted`, `campaign.scheduled`, `campaign.queued`, `campaign.sending`, `campaign.testing`, `campaign.sent`, `campaign.canceled`, `campaign.archived`

Per il significato di ogni evento, vedi Tipi di evento.

Restituisce

okboolean

true se l’endpoint ha risposto con uno stato 2xx.

status_codeinteger

Lo stato HTTP del tuo endpoint. 0 se Emailit non è riuscito a connettersi, se la richiesta è andata in timeout dopo 30 secondi, se l’endpoint ha restituito un reindirizzamento (i reindirizzamenti non vengono seguiti) o se l’URL punta a un indirizzo bloccato.

bodystring

I primi 2000 caratteri della risposta dell’endpoint, oppure l’errore di connessione.

typestring

Il tipo di evento inviato.

payloadobject[]

L’array JSON esatto che è stato inviato.

Restituisce 400 se type manca o è sconosciuto, 404 se il webhook non esiste e 429 quando superi il limite dei test.

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

Ruota il secret di firma

Genera un nuovo secret di firma per il webhook e lo restituisce. Richiede una chiave API con il permesso full.

Il vecchio secret smette subito di essere usato: ogni richiesta inviata dopo la rotazione, compresi i nuovi tentativi di eventi precedenti, viene firmata con il nuovo secret. Non c’è un periodo di sovrapposizione, quindi aggiorna il secret nel tuo endpoint subito dopo la rotazione, oppure accetta entrambi i secret per un breve periodo durante il passaggio. Vedi Verifica le firme dei webhook.

POST/webhooks/{id}/reset-secret

Parametri di percorso

idstringobbligatorio

L’ID del webhook (wh_…) o il nome del webhook.

Restituisce

Restituisce l’oggetto webhook con il nuovo secret (whsec_ seguito da 64 caratteri esadecimali). Restituisce 404 se il webhook non esiste.

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

Ritenta le richieste non riuscite

Rimette in coda per la consegna tutte le richieste di questo webhook non riuscite definitivamente negli ultimi 7 giorni. Richiede una chiave API con il permesso full.

Una richiesta non riesce definitivamente dopo l’ultimo nuovo tentativo automatico (11 tentativi nell’arco di diversi giorni; vedi Nuovi tentativi ed errori). Le richieste ritentate ripartono con un calendario completo di nuovi tentativi e vengono consegnate entro pochi secondi. Se almeno una richiesta viene messa in coda e il webhook era disattivato, ad esempio dopo 3 giorni di errori continui, il webhook viene riattivato.

Prima correggi l’endpoint, altrimenti le richieste non riusciranno di nuovo. Per ritentare una sola richiesta, usa Ritenta una richiesta.

POST/webhooks/{id}/retry-failed

Parametri di percorso

idstringobbligatorio

L’ID del webhook (wh_…) o il nome del webhook.

Restituisce

retriedinteger

Numero di richieste rimesse in coda. 0 se non c’era nulla da ritentare; in quel caso lo stato di attivazione del webhook non cambia.

Restituisce 404 se il webhook non esiste.

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

Ritenta una richiesta

Rimette in coda per la consegna una richiesta webhook non riuscita definitivamente, con un nuovo calendario dei nuovi tentativi. Se il webhook era disattivato, viene riattivato. Richiede una chiave API con il permesso full.

In questo modo puoi ritentare solo le richieste che hanno esaurito i nuovi tentativi automatici; le richieste ancora in sospeso o in fase di nuovo tentativo restituiscono 400. Trovi gli ID delle richieste (whr_…) nella scheda Requests del webhook in Email APIWebhooks. Per ritentare in una volta sola tutto quello degli ultimi 7 giorni, usa Ritenta le richieste non riuscite.

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

Parametri di percorso

idstringobbligatorio

L’ID del webhook (wh_…) o il nome del webhook.

request_idstringobbligatorio

L’ID della richiesta webhook (whr_…).

Restituisce

retriedinteger

Sempre 1.

idstring

L’ID della richiesta rimessa in coda.

Stato	Quando
`400`	La richiesta non è in errore definitivo, oppure non ha un evento da inviare di nuovo.
`404`	Il webhook non esiste, oppure la richiesta non gli appartiene.

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