Skip to main content
Webhooks deliver real-time notifications to your server when email events occur. You configure which events to listen for and provide an endpoint URL. Nuntly sends a POST request to that URL each time a matching event happens.

​
Available events

EventDescription
email.sentThe email has been accepted for delivery
email.deliveredThe email was successfully delivered to the recipient’s mail server
email.openedThe recipient opened the email (requires open tracking on your domain)
email.clickedThe recipient clicked a link in the email (requires click tracking)
email.bouncedThe email was rejected by the recipient’s server
email.complainedThe recipient marked the email as spam
email.rejectedNuntly refused to send the email due to a policy or configuration issue
email.deliveryDelayedDelivery to the recipient is temporarily delayed
email.failedThe email could not be delivered
Open and click tracking events require tracking to be enabled on your sending domain.

​
Create a webhook from the dashboard

  1. In the dashboard, go to Webhooks
  2. Click Create Webhook
  3. Fill in the form:
    • Name. A descriptive label (for example, “Production listener”).
    • Endpoint URL. The HTTPS URL where Nuntly will send events. This URL must be owned and controlled by you.
    • Status. Set to Enabled or Disabled.
    • Events. Select at least one event type to listen for.
  4. Click Create Webhook
The Create Webhook dialog showing name, endpoint URL, status toggle, and event selection grid

​
Save your signing secret

After the webhook is created, the signing secret is displayed. Copy it immediately. It is shown only once. The confirmation dialog showing the newly created webhook signing secret
The signing secret is displayed only once. Store it securely. You will need it to verify incoming webhook requests. If you lose it, you can rotate the secret from your webhook settings.

​
Create a webhook with the SDK

You can also create webhooks programmatically: 
import { Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
});

const webhook = await nuntly.webhooks.create({
  name: 'Production Listener',
  endpointUrl: 'https://yourapp.com/api/webhooks/nuntly',
  status: 'enabled',
  events: ['email.delivered', 'email.bounced', 'email.complained'],
});

console.log('Webhook ID:', webhook.id);
console.log('Signing secret:', webhook.signingSecret); // Store this securely

​
Manage webhooks

From the webhooks list in the dashboard, you can:
  • Edit. Update the name, endpoint URL, events, or status.
  • Rotate secret. Generate a new signing secret (remember to update your application with the new value).
  • Delete. Remove the webhook entirely.
The webhooks list page showing existing webhooks with management options

​
Next steps

To implement the endpoint that receives and processes webhook events in your application, see how to handle webhook events.