Webhooks

A webhook is a type of event-driven architecture that allows one web application to communicate with another.

A webhook is essentially a user-defined HTTP callback that is triggered by an event, such as the creation of a new record in a database, a change in status of an issue on a bug tracker, or a new message on a chat application.

When the event occurs, the source system makes an HTTP request to the URL specified by the webhook, which triggers the webhook and the associated code to run. The payload of the HTTP request typically contains data related to the event, which the receiving system can use to take further action.

With Squid, you have the ability to expose webhooks and make them accessible to other internal and external services. To define a webhook, simply decorate a function within a class that extends the SquidService class with the @webhook decorator.

Example:

Backend code

import {
  SquidService,
  webhook,
  WebhookRequest,
  WebhookResponse,
} from '@squidcloud/backend';

export class ExampleService extends SquidService {
  @webhook('handleStripePayment')
  handleStripePayment(request: WebhookRequest): Promise<WebhookResponse | any> {
    // TODO - add your business logic here
    // You can use this.createWebhookResponse(...) to create a response.
  }
}

To allow Squid to discover the webhook and the rest of the functions in the same service, make sure the service is exported in the service/index.ts file:

service/index.ts

export * from './example-service';

The webhook URL takes the following format:

https://[YOUR_APP_ID].[APP_REGION].squid.cloud/webhooks/[WEBHOOK_ID]

For example, the handleStripePayment webhook exposes the following URL:

https://[YOUR_APP_ID].[APP_REGION].squid.cloud/webhooks/handleStripePayment

When developing locally, you can access the webhook using this URL:

https://[YOUR_APP_ID]-dev-[YOUR_SQUID_DEVELOPER_ID].[APP_REGION].squid.cloud/webhooks/handleStripePayment

When deploying to the dev environment, you can access the webhook using this URL:

https://[YOUR_APP_ID]-dev.[APP_REGION].squid.cloud/webhooks/handleStripePayment

The request object provides the full HTTP context, such as the query parameters, body, headers, and more.

The following example code uses Squid's backend SDK to turn a Squid AI Agent into an API, which replaces using the Squid Client SDK.

Backend code

import { secureAiChatbot, SquidService, webhook } from '@squidcloud/backend';
import { WebhookRequest } from '@squidcloud/client';

export class ExampleService extends SquidService {
  @secureAiAgent('chat')
  allowChat(): boolean {
    return true;
  }

  @webhook('askQuestion')
  async askQuestion(request: WebhookRequest): Promise<string> {
    if (!request.body?.question) throw new Error('MISSING_QUESTION');

    const p: Promise<string> = new Promise((resolve, reject) => {
      let res = '';
      this.squid
        .ai()
        .agent('AGENT_ID') // Name of the profile you created earlier in that same integration
        .chat(request.body.question)
        .subscribe({
          next: (answer) => {
            res = answer;
          },
          error: () => reject('INTERNAL_ERROR'),
          complete: () => {
            resolve(res);
          },
        });
    });
    return await p;
  }
}

To see the full SDK reference documentation for the webhook decorator, click here.