Webhooks

Introduction

ROQ provides webhooks to notify your application when an event happens in your account. Webhooks are useful for asynchronous events, like when a conversation is created through chat, when a user is signed up, or when a file is uploaded. ROQ uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Events overview

At the moment, ROQ is providing events for the following entities: Users, User invites, Conversations, Messages, Files and actions: Insert, Update, Remove.

If you registered a webhook endpoint to receive some event, this will be sent to your endpoint as part of a POST request. Entity objects in the payload will be the same as you can receive through Backend SDK.

Here is an example of a webhook payload:

{
  "name": "ROQ_USER_INSERT",
  "id": "user-id",
  "object": "user",
  "data": {
    "current": {
      "reference": "user-reference",
      "email": "user-email",
      "locale": "user-locale",
      "tenantId": "user-tenant",
      "phone": "user-phone",
      "firstName": "user-firstName",
      "lastName": "user-lastName",
      "avatarUrl": "user-avatarUrl",
      "timezone":  "user-timezone",
      "active": true,
      "customData": null,
      "id": "user-id",
      "isOptedIn": true,
      "createdAt": "user-createdAt",
      "updatedAt": "user-updatedAt"
    },
    "previous": null
  },
  "environmentId": "your-environment-id"
}

How to start using webhooks in your project?

Login into your project in the ROQ Console (opens in a new tab) and select the environment where you want to enable webhooks.
Navigate to Developer Tools → Webhooks and click Enable Webhook.

Specify the URL

The endpoint where the system will send notifications when entities are created, updated, or deleted. Make sure to provide a valid URL that can receive and process these messages. Note that the URL should be publicly accessible and secure, as sensitive information may be included in the notifications.

Set the Timeout (Set the time limit, in seconds, for a webhook request to complete before timing out. This helps prevent hanging requests and optimizes server resources.)
Select the events you want to receive (Files, Users, Chat conversations, Chat messages, and User invites.)
Save your settings by hitting the SAVE button in the page's header.
Webhooks are now enabled on your environment. You are ready to start working with them.

How to create a webhook endpoint

Creating a webhook endpoint is no different from creating an endpoint in your API. We recommend using an HTTPS endpoint for publicly accessible APIs.

ROQ does not allow setting up several URLs, so you should use one endpoint to handle all event types. Based on event.name, you can have different logic for the specific event type.

Your endpoint must quickly return a successful status code (2xx) before any complex logic that could cause a timeout. Alternatively, you can configure a longer timeout in the Console UI.

How to test webhook endpoint locally

As your local machine is not publicly available, our remote API cannot call to it, so we recommend using some external tooling to proxy the request during development. You can try an open-source Ngrok (opens in a new tab). You can set the proxied URL using Console UI.

How to secure webhook endpoint (recommended)

We recommend verifying the request incoming to your webhook endpoint to be sure that it didn’t come from a server acting like ROQ.

ROQ sends a roq-platform-webhook-key header with any request triggered on a specific event, and it can be used on your side for validating the sender.

The ROQ_WEBHOOK_KEY secret can be copied along with all other environment variables at the moment when the webhook feature is enabled for this environment in the Console UI. You can use SDK for validating the roq-platform-webhook-key value.

await client.verifyWebhookHeader(headers['roq-platform-webhook-key']);

Webhook re-try mechanism

In some cases, your webhook endpoint can respond with an error code (e.g., 5xx). ROQ handles such cases with a re-try mechanism that will re-trigger webhook calls every 30 minutes * N, where N is the number of re-try. We will re-trigger the event five times max.

Postgres Save Data in Application