Skip to main content
Webhooks allow your application to receive real-time HTTP notifications when Activities and Events occur during a conversation. You can configure a webhookUrl for your Agent as well as a webhookSecret, and Monsteria will send a POST request to that URL when relevant Activities and Events happen. Upon failure to deliver, Monsteria will retry 3 additional times. After that, it will retry once every hour for 14 days before giving up. Webhooks are primary way for Agents to provide output and request additional context from your systems. Responses from webhooks will influence the conversation flow of an ongoing Thread. Handling webhooks effectively allows your Agents to interact with your systems in real-time, allowing for dynamic and context-aware conversations and actions to be taken programmatically.

​
Expected Response

Your webhook endpoint must return an application/json response with a response property that is a string. The webhook will be considered failed if the response is not a 2xx HTTP status code or if the response body does not match the expected structure. If the Agent is configured to wait for response for an Event but the webhook fails, the Agent will halt processing the Thread until a successful webhook response is received upon later retries. 
{
  "response": "Additional context for the `Agent` here."
}

​
Event Webhook Payload

The webhook payload sent to your webhook endpoint when an Event occurs will match the following structure 
{
  "notificationId": "b08b0a09-c2d1-4fbe-b1f4-e6903ec3517d",
  "notificationType": "EVENT",
  "payload": {
    "id": "2b9bdd32-2f41-4bdd-8eb2-4b50071a5909",
    "eventConfigId": "ab3a07a2-7c30-462a-b250-a9228be8a885",
    "extractedData": {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+1234567890",
      "preferredDateTime": "2025-10-10T14:30:00Z"
    },
    "activityId": "e0ada8f1-9a41-42e8-8a45-4aa9ddcb01a5",
    "threadId": "5ba88832-76c3-4220-992e-11bc4d05824f",
    "createdAt": "2025-10-07T12:34:56.789Z",
    "updatedAt": "2025-10-07T12:34:56.789Z"
  }
}
  • notificationId: The unique identifier for the Webhook notification.
  • notificationType: The type of notification, which will be EVENT for Event webhooks.
  • payload: The main payload containing Event details.
    • id: The unique identifier for the Event.
    • eventConfigId: The id of the corresponding EventConfig used to extract the Event.
    • extractedData: Data extracted from the Event. This will match the structure defined in the EventConfig schema.
    • activityId: The id of the Activity associated with the Event.
    • threadId: The Monsteria Thread associated with the Event.
    • createdAt: Timestamp when the Event was created (ISO 8601 format).
    • updatedAt: Timestamp when the Event was last updated (ISO 8601 format).

​
Activity Webhook Payload

The webhook payload sent to your webhook endpoint when an Activity occurs will match the following structure 
{
  "notificationId": "583f0b12-7cae-4f73-954b-14f0e097e1c9",
  "notificationType": "ACTIVITY",
  "payload": {
    "id": "c7b58f93-9446-4468-a7a0-0f236c7f5bf4",
    "agentId": "b974640d-098f-42a1-933a-29e3717c3e47",
    "channelProvider": "GMAIL" | "OUTLOOK",
    "threadId": "58cbb61b-1739-4af0-adc5-fe85ca9952dc",
    "direction": "INBOUND" | "OUTBOUND",
    "externalReferenceId": "string",
    "scheduledAt": "2025-10-07T12:34:56.789Z",
    "transcript": "string",
    "status": "DRAFTED" | "SCHEDULED" | "IN_PROGRESS" | "COMPLETED",
    "metadata": {},
    "fromName": "string",
    "from": "string",
    "to": ["string"],
    "cc": ["string"],
    "bcc": ["string"],
    "subject": "string",
    "body": "string",
    "createdAt": "2025-10-07T12:34:56.789Z",
    "updatedAt": "2025-10-07T12:34:56.789Z"
  }
}
  • notificationId: The unique identifier for the notification.
  • notificationType: The type of notification, which will be ACTIVITY for Activity webhooks.
  • payload: The main payload containing Activity details.
    • id: The unique identifier for the Activity.
    • agentId: The ID of the agent associated with the Activity.
    • channelProvider: The provider of the channel (e.g., GMAIL, OUTLOOK).
    • threadId: The thread associated with the Activity.
    • direction: The direction of the Activity (INBOUND or OUTBOUND).
    • externalReferenceId: links to the corresponding message entity in GMAIL or OUTLOOK system.
    • scheduledAt: The scheduled time for the Activity (ISO 8601 format).
    • transcript: The transcript of the Activity.
    • status: The current status of the Activity.
    • metadata: Any additional metadata associated with the Activity.
    • fromName: The name of the sender.
    • from: The email address of the sender.
    • to: An array of recipient email addresses.
    • cc: An array of CC email addresses.
    • bcc: An array of BCC email addresses.
    • subject: The subject of the email.
    • body: The body content of the email.
    • createdAt: The timestamp when the Activity was created.
    • updatedAt: The timestamp when the Activity was last updated.
  • response: A string that will be added as additional context for the Agent handling the Thread. This allows your webhook to influence the Agent’s behavior or provide feedback.
Return a 2xx HTTP status code to acknowledge successful receipt. Any other status code will be treated as a failure, and Monsteria will retry delivery.

​
Security

You can configure a webhookSecret for your agent. Monsteria will include this secret as X-Monsteria-Webhook-Secret header in each request so you can verify authenticity.
For more details, see the API reference or contact support.