Overview

Webhooks are how web services notify each other of events. On Waypoint, customers typically use webhooks take action after an email event like a 'bounce' or 'delivery' has happened. For example, posting a notification in a Slack channel whenever an email bounces or is marked as spam.

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.DELIVERED
• EMAIL_MESSAGE.CLICKED
• EMAIL_MESSAGE.COMPLAINT_FILED
• EMAIL_MESSAGE.CONTACT_UNSUBSCRIBED

Webhook event example

For EMAIL_MESSAGE.DELIVERED, here is a sample payload:

Copy
{
  "createdAt": "2024-10-10T21:16:25.749Z",
  "emailMessageId": "em_R7kzKeQx7AHbQSCy",
  "id": "log_Hvq9HzAzgzi3gKwV",
  "message": "Email successfully delivered to support@usewaypoint.com. Delivery time: 1 second.",
  "updatedAt": "2024-10-10T21:16:25.749Z"
}

View our full catalog of event types with additional descriptions and example payloads.

Manage webhooks on waypoint

In order to start listening to these events, first click 'Manage' next to Webhooks on your settings page. This will bring you to a separate dashboard to manage webhook endpoints and view their activity.

Adding an endpoint

⚠️ Only the owner and admins of a workspace can add endpoints. The webhooks portal is read-only for 'User' roles. Learn more about roles and permissions.

Adding an endpoint is as simple as providing an endpoint URL and a list of event types that you want to listen to.

From your webhooks dashboard, click on 'Add Endpoint':

From here, you can configure our endpoint:

💡 Pro Tip!

If you don't have a URL or your service isn't quite ready to start receiving events just yet, just press the with Svix Play button to have a unique URL generated for you.

You'll be able to view and inspect all operational webhooks sent to your Svix Play URL, making it effortless to get started.

If you don't specify any event types, by default, your endpoint will receive all events, regardless of type. This can be helpful for getting started and for testing, but we recommend changing this to a subset later on to avoid receiving unexpected messages.

Slack and Zapier integrations

Using Slack or Zapier? Use our integrations make it even easier to connect and transform data as needed.

Testing your endpoint

The easiest way to be more confident in your endpoint configuration is to start receiving events as quickly as possible.

To do this, we recommend going to one of your templates and clicking 'Send test':

After sending, you can view the resulting logs on your endpoint page within your webhooks dashboard:

Drill down into the individual log to view the payload, any attempts, and whether it succeeded or failed.

Webhook signature verification

Webhook signatures is your way to verify that webhook messages are sent by us. For a more detailed explanation, check out this article on why you should verify webhooks.

How to verify webhooks

Our webhook partner Svix offers a set of useful libraries that make verifying webhooks very simple. Here is a an example using Javascript:

Copy
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 instructions and examples of how to verify signatures, check out their webhook verification documentation.

Retries

Webhook messages are delivered with a retry schedule using an exponential backoff.

The schedule

Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

• 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 delivery attempts to the endpoint will be disabled as well.

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

Manual retries

You can also use the webhook dashboard to manually retry each message at any time, or automatically retry ("Recover") all failed messages starting from a given date.