Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Notify. Webhooks can be useful to know when users have successfully setup Notify, or paused notifications. For example, you may want to display a different message in their settings page, or only send push notifications when you know they have a connection.

Registering webhooks

To register a new webhook, you need to have a URL in your app that Notify can call. You can configure a new webhook from the Notify settings dashboard under Webhooks. Give your webhook a name, and add your URL.

Now, whenever something of interest happens, a webhook is fired off by Notify. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

When your app receives a webhook request from Notify, check the event attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a connection, notification, etc.

{
  "event_id": "evt_ck7qhp33c68tov35spng",
  "event": "connection.created",
  "timestamp": "2023-09-24T03:11:32.456Z",
  "data": {
    "connection_id": "con_ck76b3r3c68otqfg5c3g"
    // ...
  }
}

In the example above, a connection was created, and the payload type is a connection.

Event types

{
  "event": "connection.updated",
  "event_id": "evt_ck7to833c68r1r7g5cfg",
  "timestamp": "2023-09-26T05:02:16.826Z",
  "data": {
    "user_id": "your-users-id",
    "status": "paused",
    "connection_id": "con_ck76b3r3c68otqfg5c3g"
  }
}

Retry policy

If your webhook fails to respond with a status of 200, we attempt 5 retries using an exponential backoff. You can see the status of all events on the Logs page.

• 5min from last attempt
• 30min from last attempt
• 2h from last attempt
• 5h from last attempt
• 10h from last attempt

Security

To know for sure that a webhook was, in fact, sent by Notify instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-notify-signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

const signature = req.headers['x-notify-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the x-notify-signature header, you can be sure that the request was truly coming from Notify. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Notify. Don't commit your secret webhook key to GitHub!