# Delivery and bounce webhooks

Source: https://catalystgroup.gg/docs/email-delivery/delivery-webhooks/
Updated: 2026-10-19 · By Duane Garner

Let SendGrid, Mailgun, Postmark, Brevo or your own tool report delivered, bounced and spam events back into the CRM-NG SMTP email log.

Delivery webhooks let your mail service tell your site what happened to each email after it was sent: delivered, bounced, deferred, dropped or reported as spam. CRM-NG SMTP records the result on the matching log entry. This article explains the shared secret, the webhook address for each provider, and how events are matched. It is for administrators who want proof of delivery or a quick way to spot bounces.

 

## How it works

 
1. You choose a **shared secret** in CRM-NG SMTP.
2. In your mail service, you add a webhook that points at your site and includes that secret.
3. Each time something happens to a message, the service sends an event to your site.
4. CRM-NG SMTP checks the secret, reads the event and updates the **Delivery status** of the matching log entry.

 

The email log must be on. See [Setting up the email log](https://catalystgroup.gg/docs/email-delivery/email-log-setup/).

 

## Step 1: Set a shared secret

 
1. Open the Alerts tab
  Go to **CRM-NG SMTP → Settings → Alerts** and scroll to **Delivery and Bounce Webhooks**.
2. Choose a secret
  Make up a long random string, at least 32 letters and numbers, and type it into **Shared secret**. A password manager's generator works well.
3. Save
  Press **Save Alert Settings**. The box then shows **Secret saved**.
4. Keep a copy
  The secret is stored encrypted and not shown again. Keep it somewhere safe; you need it in the next step.

 

> **No secret, no webhooks:** Until a shared secret is saved, your site rejects every delivery event. This keeps the feature switched off by default.

 

## Step 2: Build the webhook address

 

The address is your site's home page with one query parameter that names the provider:

 

```
https://www.example.com/?crmng-smtp-local-delivery=<provider>
```

 

Use one of these provider values:

 

| Provider | Value | Address |
| --- | --- | --- |
| SendGrid | sendgrid | https://www.example.com/?crmng-smtp-local-delivery=sendgrid |
| Mailgun | mailgun | https://www.example.com/?crmng-smtp-local-delivery=mailgun |
| Postmark | postmark | https://www.example.com/?crmng-smtp-local-delivery=postmark |
| Brevo | brevo | https://www.example.com/?crmng-smtp-local-delivery=brevo |
| Anything else | generic | https://www.example.com/?crmng-smtp-local-delivery=generic |

 

The **Alerts** tab shows the SendGrid version for your own site under the **Shared secret** box. Change the last word for other providers.

 

## Step 3: Send the secret with each event

 

The help text reads: **Send the secret in the X-CRMNG-SMTP-Webhook-Key header. A key query parameter is also accepted for providers that cannot set headers.**

 
- **If your provider lets you add custom headers:** add a header named `X-CRMNG-SMTP-Webhook-Key` with your secret as its value. This is the safer choice, because headers do not appear in server logs.
- **If it does not:** add `&key=` and your secret to the end of the address, for example `https://www.example.com/?crmng-smtp-local-delivery=mailgun&key=YOUR-SECRET`.

 

Requests with a missing or wrong secret are refused with a "403 Forbidden" answer.

 

## Step 4: Add the webhook at your provider

 

In your provider's dashboard, look for a page whose current name is similar to "Webhooks", "Event Webhook" or "Event notifications". Paste the address, add the secret as above, and choose which events to send. Pick delivery, bounce, deferral, drop and spam complaint events. Open and click events are ignored, because CRM-NG SMTP counts those itself. See [Open and click tracking](https://catalystgroup.gg/docs/email-delivery/open-and-click-tracking/).

 

Most providers have a "send test" button. A successful test answers with a small JSON message such as `{"success":true,"data":{"processed":1,"matched":0}}`. `matched` is 0 for test events because their addresses were never logged.

 

## Events CRM-NG SMTP records

 

| Event name sent by the provider | Shown as |
| --- | --- |
| delivered, delivery | delivered |
| processed | processed |
| bounce, bounced, hard_bounce | bounced |
| deferred | deferred |
| dropped | dropped |
| spamreport, spamcomplaint, complaint | complained |

 

Any other event name is skipped. Provider event names vary: for example, an event a provider calls "failed" or "soft_bounce" is not one of the names above and does not change the log.

 

## The generic format

 

For your own tools, or a provider without a built-in format, send a `POST` with a JSON body like this to the `generic` address:

 

```
{ "email": "jane@example.com", "status": "delivered", "log_id": 0 }
```

 

`status` must be one of the event names in the table. `log_id` is optional; set it to a log entry's number if you know it.

 

## How events are matched to log entries

 

The help text explains: **Events without crmng_smtp_log_id are correlated to the latest log for the recipient.** CRM-NG SMTP does not add a log ID to outgoing messages itself, so in practice events are matched by address: the newest logged email whose **To** list contains the recipient gets the update. CC and BCC recipients are not matched. Each new event replaces the previous value.

 

See the result by opening an entry on the **Email Log** tab and reading **Delivery status**. For what each value means, see [Understanding delivery status](https://catalystgroup.gg/docs/email-delivery/delivery-status/).

 

## Related

 
- [Understanding delivery status](https://catalystgroup.gg/docs/email-delivery/delivery-status/)
- [Viewing the email log](https://catalystgroup.gg/docs/email-delivery/viewing-the-email-log/)
- [SendGrid](https://catalystgroup.gg/docs/email-delivery/mailer-sendgrid/)
- [Mailgun](https://catalystgroup.gg/docs/email-delivery/mailer-mailgun/)
- [Postmark](https://catalystgroup.gg/docs/email-delivery/mailer-postmark/)
- [Brevo (formerly Sendinblue)](https://catalystgroup.gg/docs/email-delivery/mailer-brevo/)