Webhooks

Webhooks are how web services notify each other when something happens. On Waypoint, customers usually use them to react to email events like a bounce or delivery — for example, posting to a Slack channel whenever an email bounces or is marked as spam.

Send webhook events

On our Free and Starter plan, the following event type is available:

• EMAIL_MESSAGE.DELIVERED

On our Growth and Pro plans, the following event types are available:

• EMAIL_MESSAGE.CREATED
• EMAIL_MESSAGE.SENT
• EMAIL_MESSAGE.CLICKED
• EMAIL_MESSAGE.DELIVERED
• EMAIL_MESSAGE.OPENED
• EMAIL_MESSAGE.COMPLAINT_FILED
• EMAIL_MESSAGE.BOUNCED
• EMAIL_MESSAGE.CONTACT_UNSUBSCRIBED

Webhook event example

For EMAIL_MESSAGE.DELIVERED, here is a sample payload:

{
  "createdAt": "2025-04-21T14:03:01.357Z",
  "eventType": "EMAIL_MESSAGE.DELIVERED",
  "emailMessage": {
    "bcc": [],
    "cc": [],
    "createdAt": "2025-04-21T14:02:57.209Z",
    "deliveredAt": "2025-04-21T14:02:58.357Z",
    "erroredAt": null,
    "firstBouncedAt": null,
    "firstClickedAt": null,
    "firstComplainedAt": null,
    "firstOpenedAt": null,
    "from": "Waypoint Demo <support@usewaypoint.com>",
    "id": "em_wUpG2hHHvfncz8EY",
    "lastBouncedAt": null,
    "lastClickedAt": null,
    "lastComplainedAt": null,
    "lastOpenedAt": null,
    "lastSuppressedAt": null,
    "lastUnsubscribedAt": null,
    "metaId": null,
    "metadata": {},
    "processedAt": "2025-04-21T14:03:00.506Z",
    "referenceId": "0100019658a8cf8d-727795ad-c4f4-44a8-afaa-4d0ea08aa8bd-000000",
    "replyTo": "",
    "sentAt": "2025-04-21T14:03:00.365Z",
    "source": "PREVIEW",
    "status": "SUCCEEDED",
    "to": [
      "jordan@usewaypoint.com"
    ],
    "type": "EmailMessage",
    "updatedAt": "2025-04-21T14:03:01.558Z",
    "variables": {
      "source": "Waypoint"
    },
    "waypointTemplateId": "wptemplate_MXiSMZJrrUrNb3Xh"
  },
  "emailMessageId": "em_wUpG2hHHvfncz8EY",
  "id": "log_vJayu2MEA7ZZXTuQ",
  "message": "Email successfully delivered to jordan@usewaypoint.com. Delivery time: 0.2 seconds.",
  "updatedAt": "2025-04-21T14:03:01.357Z"
}

Manage webhook sending on Waypoint

To start listening for events, click ‘Manage’ next to Webhooks on your settings page. That opens a dedicated dashboard for managing endpoints and viewing their activity.

Adding a webhook endpoint

Permissions

Only the owner and admins of a workspace can add endpoints. The webhooks portal is read-only for ‘User’ roles.

To add an endpoint, you just need a URL and the event types you want to listen for.

From your webhooks dashboard, click ‘Add Endpoint’:

From here, you can configure your endpoint:

Testing Webhooks

Don’t have a URL handy or service ready to receive events? Use the with Svix Play link to generate a unique URL where you can view and inspect every webhook sent to it.

If you don’t specify any event types, your endpoint receives everything by default. That’s handy for testing, but switch to a subset later so you’re not flooded with events you don’t need.

Slack and Zapier integrations

Using Slack or Zapier? Our integrations make it easy to connect and transform the data however you need.

Testing your endpoint

The fastest way to make sure your endpoint is set up correctly is to send it a real event.

Open one of your templates and click ‘Send test’:

Once sent, you can view the resulting logs on your endpoint page in the webhooks dashboard:

Open a log to see the payload, attempt history, and whether it succeeded or failed.

Webhook signature verification

Webhook signatures let you confirm that an incoming message actually came from us. For background, see why you should verify webhooks.

Verify webhooks

Our webhook partner Svix has libraries that make verification easy. Here’s a JavaScript example:

import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
const headers = {
"svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
"svix-timestamp": "1614265330",
"svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
const payload = wh.verify(payload, headers);

For more examples, see Svix’s webhook verification docs.

Retries

Failed webhook deliveries are retried on an exponential backoff schedule.

The schedule

Each message is retried on this schedule, with each interval starting after the previous attempt fails:

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (in addition to the previous)

If an endpoint is removed or disabled, retries for it stop too.

For example, a message that fails three times before succeeding will be delivered roughly 35 minutes and 5 seconds after the first attempt.

Manual retries

You can retry any message manually from the webhook dashboard, or use “Recover” to retry all failed messages from a given date.

Receiving webhooks

Want to send emails when other services send you webhooks? See receiving webhooks with workflows.