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.

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

  "payload": {
    "chatId": "WAz8eIbvDR60rouK"
    // ...

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

Event types

  • Name

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

Example payload

  "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


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.


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.