Skip to content
AskVault Docs
Try Free →

The custom_webhook skill

Written by , Principal Architect, Networks and Tech, AskVault · Reviewed by Allison Chan
Last updated: · 5 min read

What the skill does

The 13 first-party AskVault skills cover most patterns: lead capture, escalation, scheduling, order status, sentiment routing. The 14th skill, custom_webhook, is the escape hatch for everything else.

When trigger phrases match, the skill calls a webhook you configure with the conversation context. Your endpoint does whatever it wants: write to a database, trigger a workflow, call an API we don't have a native integration for, fire a Slack message with custom formatting.

The skill is on Business and above. Business+

Real use cases

Five patterns we see most often:

  • CRM other than HubSpot or Salesforce. Pipedrive, Close, Copper, Insightly. Webhook hits your CRM's API.
  • Custom internal systems. Your home-grown ticketing, inventory, or returns systems. Webhook bridges to your backend.
  • Real-time order status from a non-Shopify, non-WooCommerce store. Magento, BigCommerce, custom Rails store. Webhook calls your store's API.
  • Slack notifications with custom formatting. Beyond AskVault's built-in Slack alerts. Webhook fires to Slack's webhook with your specific message template.
  • Trigger a Zapier or Make workflow. Webhook is the universal hand-off to any "no-code" automation product.

Setup

Configure under AI Agents > Skills > custom_webhook:

  1. Enable the skill.
  2. Webhook URL. Where AskVault POSTs when the skill fires.
  3. Authentication. A single custom header — use it as a Bearer token (name it Authorization) or as an API key under whatever header name your endpoint expects. The value is stored encrypted.
  4. Trigger phrases. What customer messages trigger the webhook. Example: "create a ticket", "log this to Pipedrive", "send this to my team".
  5. Request schema. Define the fields that go in the POST body — see below.

Test the webhook configuration under Skills > custom_webhook > Test. AskVault fires a sample request to your URL and shows you the response.

Request payload

You define a JSON Schema for the parameters this action needs — field names, types, which are required — under AI Agents > Skills > custom_webhook. When the skill fires, the bot fills in those parameters from the conversation, and AskVault POSTs exactly that object as the JSON body to your webhook URL. For example, a schema with ticket_subject, priority, and customer_email fields produces a request body like:

{
  "ticket_subject": "Can't log in to my account",
  "priority": "high",
  "customer_email": "jane@example.com"
}

The shape is entirely up to your schema — there's no fixed envelope of conversation/customer metadata added around it.

Response handling

Return HTTP 200 with a JSON body describing what happened. AskVault passes that body back to the LLM as context, and the bot synthesizes it into a natural-language reply — there's no required reply field it extracts verbatim, so keep the response reasonably self-explanatory (status, any ID the customer would want, a short message). A status code >= 400 makes the bot say something generic like "I tried to do that but something failed; let me get a human."

Security

The custom_webhook skill authenticates itself with the custom header you configured above — it does not sign requests with HMAC. If your endpoint needs to reject anything that isn't a real AskVault call, require and check that header server-side:

function verifyAskVaultRequest(req, expectedHeaderName, expectedValue) {
  return req.headers[expectedHeaderName.toLowerCase()] === expectedValue;
}

Anyone who guesses your webhook URL but doesn't know the header value can't get past this check. Rotate the header value from Skills > custom_webhook if you suspect it's leaked.

(AskVault's separate outbound event webhooks — for events like conversation.resolved and lead.captured — do HMAC-sign every delivery with X-AskVault-Signature; that's a different feature from this skill.)

Policy bounds

The skill respects a rate limit: up to 60 invocations per workspace per hour. This is a fixed platform default, not a per-workspace tunable setting. Hitting it surfaces a polite fallback to the customer.

Latency

End-to-end latency depends on your webhook's response time:

  • AskVault's overhead: about 200 ms.
  • Your webhook: as fast as it returns.

Total. If your webhook takes 2 seconds, the bot's reply takes about 2.2 seconds. Keep webhook latency under 3 seconds for good UX. Anything slower and the bot pre-sends a "working on it..." message, then replaces it with the real reply once your webhook returns.

For very slow operations (10+ seconds), use a fire-and-forget pattern: webhook returns immediately, completes the work async, and follows up via the conversations API.

Limits

  • Plan availability. Business and above.
  • Request body size. Up to 64 KB. Conversations longer than this get the most recent 64 KB.
  • Response timeout. 15 seconds. Beyond that, AskVault assumes failure.
  • Per-conversation invocations. Default 3, hard max 10.

Common pitfalls

Webhook never fires. Trigger phrase doesn't match. Test with exact phrases under Skills > custom_webhook > Test.

Auth header check fails. Header value mismatch between AskVault and your endpoint. Re-copy the value from the dashboard and update your endpoint.

Reply reads oddly. The bot synthesizes its reply from whatever JSON your endpoint returns — keep the response body self-explanatory (status, any ID the customer would want, a short message) so the LLM has something clear to phrase.

Bot says generic error. Your webhook returned >= 400. Check your endpoint's logs and AskVault's webhook delivery history under Dashboard > Webhooks > Deliveries.

Per-conversation invocation cap hit. Customer keeps triggering the same intent. Either loosen the cap, or refine your trigger phrases to be more selective.

FAQ

Can the bot call multiple webhooks per conversation?

Yes, sequentially. The skill fires when any of its trigger phrases match. You can configure multiple custom_webhook skill instances with different webhook URLs and trigger lists.

Can I return JSON other than the standard schema?

Yes — there is no standard response schema to match. Return whatever JSON shape makes sense for your endpoint; it's passed to the LLM as context and the bot phrases a reply from it.

Is there an idempotency mechanism?

Yes, on AskVault's side: an identical call (same workspace, action, and parameters) within a short window is served from cache instead of hitting your endpoint again, so you don't need to build your own dedup for that case. AskVault doesn't retry on success; on 5xx failures it retries up to 2 more times (configurable per action).

Can the skill fire on every message instead of by trigger phrase?

Yes. Set the trigger to a wildcard match under Skills > custom_webhook > Trigger Mode = always. The webhook fires on every customer message in the conversation. Use sparingly; rate limits apply.

Was this page helpful?