Skip to main content

​
What are Webhooks in AMS?

Webhooks allow you to be notified when changes are made to parts of the Mindset AI system—without needing to repeatedly check by calling an API. You can use webhooks to:
  • Be notified of changes made by users to the agent configuration
  • Monitor the processing status of files you send to the ContextFiles API for ingestion
  • Track when contexts are created, updated, or deleted
  • Receive notifications when agents are modified
When these events occur, you’ll automatically receive notifications at your specified endpoint.

​
Accessing Webhooks in AMS

1

Log in to AMS

Log in to your AMS application
2

Navigate to Configure

Go to the Configure section in the sidebar
3

Select API Management

Click on API Management
4

Open Webhooks Tab

Click on the Webhooks tab

​
Webhook Dashboard

​
Overview Section

At the top of the Webhooks tab, you’ll see:

Webhook Counter

Shows how many webhooks you’ve configured (e.g., “3 of 50 Webhooks”)

Help Link

Opens documentation for webhook integration

New Webhook Button

Create a new webhook (disabled if you’ve reached the 50 webhook limit)

​
Webhook List

The main area displays all your configured webhooks with:
  • Search Bar: Find webhooks by name
  • Filter Dropdown: View all webhooks, only active ones, or only inactive ones
  • Webhook Cards: Each card shows webhook details (see below)

​
Understanding Webhook Cards

Each webhook is displayed as a card with the following information:
  • Icon: Building blocks icon identifying the webhook
  • Webhook Name: The descriptive name you assigned
  • Endpoint URL: The HTTPS endpoint that receives notifications
  • Status Badge:
    • Active (green): Webhook is currently sending notifications
    • Inactive (gray): Webhook is paused

​
Creating a New Webhook

​
Step 1: Open the Dialog

Click the New Webhook button at the top of the webhook list.

​
Step 2: Fill in the Details

Webhook Name (Optional)

Purpose: A descriptive label for this webhookCharacter Limit: 0-50 charactersExamples:
  • “Production Event Sync”
  • “Staging Notifications”
While the name field is optional in the AMS UI, providing a name is recommended. If you create a webhook without a name using the API, you won’t be able to edit it in AMS without also giving it a name.
Purpose: The HTTPS endpoint that will receive webhook notificationsCharacter Limit: 0-500 charactersFormat: Must be a valid HTTP or HTTPS URLExample: https://your-platform.com/webhooks/mindsetValidation:
  • Must start with http:// or https://
  • Must have a valid domain name
  • No special protocols (javascript:, data:, file:) allowed
Security: Use HTTPS in production environments.
Select which resource types trigger this webhook:
  • ☐ Agents: Notified when agents are created, updated, or deleted
  • ☐ Contexts: Notified when contexts are created, updated, or deleted
  • ☐ Context Files: Notified when files are created, updated, or deleted
Select only the entities you need to reduce unnecessary notifications.
Toggle Switch: Enable or disable the webhook
  • Active: Webhook will send notifications immediately
  • Inactive: Webhook is saved but won’t send notifications

​
Step 3: Save

  1. Click the Save button
  2. A success message appears: “Webhook created successfully”
  3. The new webhook appears in your list

​
Step 4: Copy Your Secret

Important: Copy and save the webhook secret immediately!
1

Find Your Webhook

Locate your new webhook in the list
2

Copy the Secret

Click the Copy secret button
3

Store Securely

Store the secret securely (you’ll need it to verify webhook signatures)
The secret format looks like: whsec_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6

​
Editing an Existing Webhook

​
To Edit a Webhook:

1

Find the Webhook

Locate the webhook in the list
2

Open Menu

Click the ⋮ menu on the right side
3

Select Edit

Choose Edit from the menu
4

Modify Settings

Change any of the following:
  • Webhook name
  • Endpoint URL
  • Entity types
  • Active/Inactive status
5

Save Changes

Click Save
You cannot change the webhook secret. The secret is auto-generated and permanent for each webhook.

​
Real-Time Validation

As you type, the form validates your input:

Name Field

Shows character counter (e.g., “25/50”)

URL Field

Shows error if invalid or empty

Save Button

Only enabled when all required fields are valid

Character Counters

Show remaining characters in real-time

​
Managing Webhooks

​
Activate/Deactivate

  1. Click the ⋮ menu on the webhook card
  2. Select Deactivate
  3. Webhook status changes to “Inactive” (gray badge)
  4. No notifications will be sent

​
Delete a Webhook

Warning: Deletion is permanent and cannot be undone.
1

Open Menu

Click the ⋮ menu on the webhook card
2

Select Delete

Choose Delete from the menu
3

Confirm Deletion

A confirmation dialog appears:
  • Title: “Delete “webhook-name”?”
  • Message: “The Webhook will be permanently deleted. This action cannot be undone.”
4

Confirm or Cancel

Click Delete to confirm (or Cancel to abort)
5

Success

Success message appears: “Webhook deleted successfully”

​
Copy Webhook Secret

To copy the secret at any time:
  1. Find the webhook in the list
  2. Click the Copy secret button (pink button on the right)
  3. Success message appears: “Webhook secret copied successfully”
  4. Paste the secret into your code or secrets manager

​
Filtering and Searching

​
Search Webhooks

Use the search bar to find webhooks by name:
1

Type in Search Field

Enter text in the search bar at the top
2

Auto-Filter Results

Results filter automatically as you type
3

Clear Search

Clear the search to show all webhooks
If no results found:
  • Zero-state message appears: “No Webhooks Match Your Search”
  • Suggestion: “Try again with a different search term”

​
Filter by Status

Use the dropdown menu to filter webhooks:

Show All

Display all webhooks (default)

Active

Show only active webhooks

Inactive

Show only inactive webhooks

​
Understanding Webhook Limits

​
Current Limits

Maximum Webhooks

50 webhooks per applicationWebhook counter shows “X of 50 Webhooks” at the top

​
When Limit is Reached

  • The New Webhook button becomes disabled (gray)
  • You must delete an existing webhook before creating a new one
Instead of creating multiple webhooks, use one webhook and filter events in your code based on event.data.externalTenantId.

​
Zero States (Empty States)

When you haven’t created any webhooks yet, you’ll see:
  • Icon: Webhook illustration
  • Title: “No Webhooks Configured”
  • Description: “Configure webhooks to receive real-time event notifications.”

​
What Happens After Creating a Webhook?

​
1. Webhook Registration

When you click Save, AMS:
1

Send Configuration

Sends your webhook configuration to the Mindset API
2

Generate Secret

Generates a unique webhook secret
3

Return Details

Returns the webhook UID and secret
4

Display Webhook

Displays the new webhook in your list

​
2. Webhook Notifications

Once active, your webhook will receive HTTP POST requests when events occur:
  • Agent created, updated, deleted
  • Context created, updated, deleted
  • Context file created, updated, deleted
Events are delivered within 5 seconds of the change
  • HTTP POST request to your endpoint URL
  • JSON payload with event details
  • Signature header for verification

​
3. Testing Your Webhook

After creating a webhook:
1

Make a Test Change

Create an agent, upload a file, etc.
2

Check Your Logs

Check your endpoint logs
3

Verify Receipt

Verify you received the webhook notification

​
Best Practices

​
Naming Webhooks

  • “Production Event Sync”
  • “Staging Notifications”
  • “Analytics Dashboard Updates”
  • “Audit Log Integration”

​
Entity Selection

  • Select only the entities you need
  • Reduces unnecessary traffic
  • Easier to process specific events

​
Security

  • Copy and save the webhook secret immediately
  • Store secrets in environment variables or secrets manager
  • Use HTTPS endpoints in production
  • Verify signatures in your code (see API guide)

​
Common Questions

No. The secret is auto-generated and permanent for each webhook. If you need a new secret, delete the webhook and create a new one.
You can retrieve it from the Agent Management Studio UI by clicking the Copy secret button on the webhook card.
Yes, but it’s not recommended. Instead:
  • Use one webhook per endpoint
  • Filter events in your code based on event type or tenant ID
Currently, webhooks use “fire-and-forget” delivery:
  • If your endpoint doesn’t respond, the event is lost
  • No automatic retries
  • Implement your own monitoring to detect missing webhooks
  • Create a separate webhook for testing
  • Use a different endpoint URL (e.g., staging environment)
  • Mark it clearly in the name (e.g., “Staging Test Webhook”)
  • Deactivate when not testing

​
Troubleshooting

​
Save Button is Disabled

Check:
Webhook name is under 50 characters (if provided)
URL is valid (starts with http:// or https://)
URL has a valid domain
URL is under 500 characters

​
Cannot Create New Webhook

Check:
You have fewer than 50 webhooks
If at limit, delete an unused webhook first

​
Validation Errors

  • “This field can’t be empty” → Enter a URL
  • “Please enter a valid URL” → Check URL format (must include http:// or https://)
  • Name: You’ve exceeded 50 characters → Shorten the name
  • URL: You’ve exceeded 500 characters → Use a shorter URL

​
Summary Checklist

When creating a webhook, make sure to:
Give it a descriptive name
Use an HTTPS URL in production
Select the appropriate entity types
Copy and securely store the webhook secret
Test the webhook with a sample event
Verify signature verification works in your code
Monitor webhook delivery in your logs

​
Next Steps

After configuring webhooks in AMS:
1

Implement Webhook Handler

See “Webhooks API - User Guide” for code examples
2

Verify Signatures

Implement HMAC-SHA256 signature verification
3

Test Thoroughly

Make changes and verify notifications arrive
4

Monitor Delivery

Track successful and failed webhook deliveries
5

Handle Errors

Implement retry logic and error alerting