Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with NexusGPT. With webhooks, your app can know when something happens in NexusGPT, such as a message written by an agent.

Registering webhooks

To specify your webhook url, you will need to go back to your Settings in the Developers panel. You will find below your API Key a field to enter your webhook url.

Once this Webhook URL set up, NexusGPT will always send you events whether you make calls with your API Key or directly on our website.

Consuming webhooks

After receiving a request from NexusGPT on your webhook, you can find the type of event that triggered the webhook in the type attribute of the request body. This will help you distinguish which type of payload you are supposed to expect, e.g., a chat, agent, etc.

Example webhook payload

{
  "event": "MESSAGE_FINALIZED",
  "payload": {
    "chatId": "WAz8eIbvDR60rouK"
    // ...
  }
}

In the example above, a message was FINALIZED, and the payload type is a Message.

See all event types

Event types

  • Name
    MESSAGE_FINALIZED
    Type
    Description

    A new message was written in one of your chatrooms by an agent.

Example payload

{
  "event": "MESSAGE_FINALIZED",
  "payload": {
    "id": "5d691de8-47f7-4e67-b12c-0a44fbf0e79b",
    "chatId": "7833b1ec-c355-4285-9f3d-60ded2878418",
    "senderType": "VIRTUAL_EMPLOYEE",
    "userSenderId": null,
    "virtualSenderId": "fa9640f5-5821-40bf-9917-a9a114063590",
    "content": "Hello! How may I help you?",
    "contentJson": {
      "content": null
    },
    "type": null,
    "status": "PROCESSED",
    "createdAt": "2023-06-29T08:27:44.519Z",
    "updatedAt": "2023-06-29T08:28:19.797Z",
    "virtualSender": {
      "id": "fa9640f5-5821-40bf-9917-a9a114063590",
      // ...
    },
    "files": [],
    "executionPlan": null
  }
}

Security

As a matter of security and to know for sure that a webhook was, in fact, sent by NexusGPT instead of a malicious actor, you can specify an header. Using the developer settings in the NexusGPT, you can enter the header key you are expecting and also the value that will be sent in the header. The header is optional but recommended to use.

Webhook

As an example, the header entered in the developer settings is: nexus-signature with value mysecret.

On every webhook request, NexusGPT will send the header key and value you specified in the developer settings, and you will have to verify that the header key and value match what you are expecting.