Manage webhook events

A webhook sends selected MailGraf events to your service as they happen. Use it when another system needs to react without polling the API, such as updating a CRM after a contact subscribes.

Add an endpoint

1. Open Settings > Webhooks

   Click Add endpoint to start a new connection.

2. Enter the destination

   Add an optional Name and the Endpoint URL. The URL must use HTTPS and resolve to a public internet address.

3. Choose events

   Select at least one event under Events. Choose only the events the receiving service processes.

4. Send a test event

   Save the endpoint, then click Send test event. A test makes one immediate delivery and does not retry after a failure.

The receiving service must return a 2xx response within seven seconds. MailGraf does not follow redirects, so a 3xx response counts as a failed delivery.

Choose the right events

Contact activity

• contact.subscribed: a contact confirms a subscription.
• contact.unsubscribed: a contact unsubscribes.
• contact.complained: a recipient reports an email as spam.
• contact.tag_added and contact.tag_removed: one tag membership changes.
• contact.list_added and contact.list_removed: one list membership changes.

Tag and list membership events come from individual actions in the contact panel, automations, forms and the public API. Bulk imports and bulk actions do not create one webhook event for every membership change.

Campaign and email activity

• campaign.sent: a campaign finishes. MailGraf sends this event once for the campaign, not once per recipient.
• email.delivered: an email is accepted as delivered.
• email.bounced: an email bounces.

Form activity

• form.submitted: a form is submitted. This happens before double opt-in confirmation, so the payload may not contain a contact ID yet.

Use contact.subscribed when the receiving system must wait for confirmed consent. Use form.submitted when it must react to the submission itself.

Follow failed deliveries

Open Recent deliveries to see the latest 50 attempts kept during the 30-day retention period. Each record shows the event, response status, attempt count and delivery time.

For a normal event, MailGraf makes up to five attempts in total. After the first failure it retries after 1 minute, 5 minutes, 30 minutes and 2 hours. Fix the receiving service before clicking Retry now on a failed delivery. A manual retry starts a new delivery cycle.

Where the full reference lives

The API reference documents MailGraf's public API contract. Webhook delivery, event selection and signing are managed under Settings > Webhooks.