---
title: Webhook Integration for Custom Handoff | usedocs
description: "Generic HTTPS webhook integration for usedocs escalations and leads. Build custom automations into PagerDuty, Zapier, or internal tools."
image: "https://usedocs.app/og.png"
url: "https://usedocs.app/integrations/webhooks"
---

Integration · Updated 2026-08-12

# Webhook integration for usedocs

Every team has a weird last-mile system. Webhooks are the escape hatch that keeps usedocs automations composable.

Need help?

Email [hello@usedocs.app](mailto:hello@usedocs.app) for product questions, setup help, sales, partnerships, or security reports.

TL;DR

## Short answer

The generic webhook integration POSTs JSON handoff and lead events to any HTTPS URL you control. Use it when Slack/Teams templates are not enough — route into Zapier, PagerDuty, custom middleware, or internal buses.

## Overview

When capabilities fire handoff or lead notifications, usedocs enqueues a notification event and delivers to active providers including a generic webhook. Your endpoint must accept HTTPS POST JSON and return 2xx. Signatures and retries follow the notification worker behavior — design idempotent consumers. Design receivers to be idempotent using event ids when present, or hash of bot+conversation+kind. Log deliveries without storing full PII if policy requires minimization. Prefer private networking or allowlisted IPs when possible. If you fan out to five systems, put a small multiplexer service behind one URL so usedocs stays simple. Alert when failure rates spike — silent webhook death means silent escalations.

## What this integration does

### Custom routing

Fan into any automation platform or internal service that accepts webhooks. Keep configuration documented in your internal runbook so new teammates can reinstall the integration without reverse-engineering the dashboard.

### Same event model

Handoff and lead payloads share structured fields for bot id, question, confidence, and contact info. Keep configuration documented in your internal runbook so new teammates can reinstall the integration without reverse-engineering the dashboard.

### No vendor lock on chat tools

If you leave Slack next year, your middleware can keep working. Keep configuration documented in your internal runbook so new teammates can reinstall the integration without reverse-engineering the dashboard.

## Setup

   01

**Stand up an HTTPS endpoint** Publicly reachable, TLS valid, idempotent handler.

   02

**Add webhook in Integrations** Paste URL, validate HTTPS, connect provider.

   03

**Enable notify flags** Capabilities → handoff / lead integrations.

   04

**Verify with a test event** Inspect logs; confirm 2xx and that retries do not duplicate side effects.

## Limits and plan notes

- HTTPS only — no http:// endpoints.
- Timeouts and non-2xx responses mark failed deliveries after retries.
- You own authentication (shared secrets in URL path or custom headers if supported by config).
- Do not log PII carelessly on your receiver.

## Not for you if…

If you only need a channel message, prefer Slack/Discord/Teams for faster setup. Webhooks are for custom automation builders.

## FAQ

### What payload format?

JSON with text/message fields suitable for generic consumers; see notification formatter for exact keys.

### Retries?

Transient failures retry with backoff; permanent failures are marked failed.

### Can we sign payloads?

Prefer private URLs or reverse proxies that verify auth; extend carefully if you add shared secrets.

### Zapier/Make?

Yes — point at their catch hooks.

### Multiple webhooks?

Provider model is typically one config per provider per bot; use a multiplexer service if you need many sinks.

### Plan gates?

Integrations may require Growth+ — confirm in billing UI.

## Connect in the dashboard

Start free, add your docs, then configure integrations under the bot settings.

				 Open dashboard

```json
[
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "name": "Home",
        "item": "https://usedocs.app/"
      },
      {
        "@type": "ListItem",
        "position": 2,
        "name": "Integrations",
        "item": "https://usedocs.app/integrations/"
      },
      {
        "@type": "ListItem",
        "position": 3,
        "name": "Webhook integration for usedocs",
        "item": "https://usedocs.app/integrations/webhooks"
      }
    ]
  },
  {
    "@context": "https://schema.org",
    "@type": "WebPage",
    "name": "Webhook Integration for Custom Handoff | usedocs",
    "description": "Generic HTTPS webhook integration for usedocs escalations and leads. Build custom automations into PagerDuty, Zapier, or internal tools.",
    "url": "https://usedocs.app/integrations/webhooks",
    "dateModified": "2026-08-12"
  },
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "What payload format?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "JSON with text/message fields suitable for generic consumers; see notification formatter for exact keys."
        }
      },
      {
        "@type": "Question",
        "name": "Retries?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Transient failures retry with backoff; permanent failures are marked failed."
        }
      },
      {
        "@type": "Question",
        "name": "Can we sign payloads?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Prefer private URLs or reverse proxies that verify auth; extend carefully if you add shared secrets."
        }
      },
      {
        "@type": "Question",
        "name": "Zapier/Make?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Yes — point at their catch hooks."
        }
      },
      {
        "@type": "Question",
        "name": "Multiple webhooks?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Provider model is typically one config per provider per bot; use a multiplexer service if you need many sinks."
        }
      },
      {
        "@type": "Question",
        "name": "Plan gates?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Integrations may require Growth+ — confirm in billing UI."
        }
      }
    ]
  }
]
```