Skip to main content

Webhooks

Introduction

Webhooks let you register a URL that we will notify anytime an event happens in your account. When the event occurs—for example, when a successful subscription is created, Rokt Calendar creates an Event object. This object contains all the relevant information about the event occurrence, including the type of event and the data associated with that event. Rokt Calendar then sends the Event object to any URLs in your account's webhooks settings via an HTTP POST request.

Configuring webhook settings

Webhooks are configured in the webhooks settings section of Rokt Calendar account. Clicking Add Webhook reveals a form to add a new endpoint URL for receiving webhooks as well as the type of event(s) you would like to subscribe to.

You can enter any URL you'd like to have events sent to, but this should be a dedicated page on your server, as per the instructions below. You can also choose to be notified of multiple event types, or only specific ones.

Webhook Configuration

Subscription event types

  • Subscribe Event: A user subscribes to a calendar.
  • Unsubscribe Event: A user unsubscribes from a calendar.
note

Webhook v1 is obsolete. The old webhook version only supports 2 basic event types. Please use Webhook v2 for more event types with the latest data payload structure.

Common webhook mistakes

  • Providing the wrong URL in the Dashboard.
  • The webhook endpoint not returning a 200 status code.

Receiving a webhook notification

Creating a webhook endpoint on your server is no different from creating any page on your website. Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an Event object.

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx codes, will indicate to Rokt Calendar that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure.

If a webhook is not successfully received for any reason, Rokt Calendar will continue trying to send the webhook for 30 minutes with a few minutes interval between each attempt.

When viewing a specific event information through the Dashboard, you can check how many times we've attempted to send an event to an endpoint by clicking on that endpoint URL in the Webhook details section. This will show you the latest response we received from your endpoint, along with a list of all attempted webhooks and the respective HTTP status codes we received. Any failed event can also be retried from the Dashboard after the 30 minutes have expired.

Best practice

  • Before going live, test that your webhook is working properly. You can do so by sending dummy test events from the webhooks settings pane. Please note that as these are fake, test events, they will not map to real objects in your account.

  • If your webhook script performs complex logic, or makes network calls, it's possible the script would timeout before Rokt Calendar sees its complete execution. For that reason, you may want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

  • Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events.