Webhooks overview

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, a user is signed up, or when a file was 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 kind of 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 GraphQL API or 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 Console (https://console.roq.tech/ (opens in a new tab)) and select the environment where you want to enable webhooks.
Navigate to Project Details -> Settings and scroll to the bottom of the page to 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 that you would like to receive (Files, Users, Chat conversations, Chat messages and User inites.)
Save your settings by hitting the "SAVE" button in the header of the page.

Webhooks are now enabled on your environment and 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 provide the option to set 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) prior to any complex logic that could cause a timeout. The other way around you can configure longer timeout in Console UI.

How to test webhook endpoint locally

As your local machine is not publicly available, our remote API is not able to 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 is sending 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. ROQ_WEBHOOK_KEY secret can be copied along with all other environment variables at the moment when the webhook feature was enabled for this environment in Console UI. You can use SDK for validating 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 re-try mechanism, that will re-trigger webhook call every 30 minutes * N, where N is number of re-try. We will try to re-trigger the event 5 times max.

UI Components Overview