Workflow Action - Custom webhook

Patient Copilot’s Custom Webhook workflow action lets you send real‑time data to external services using GET, POST, PUT, and DELETE requests. Configure auth, headers, query parameters, and JSON/form payloads to connect CRMs, apps, and custom APIs—without code. This article explains setup, best practices, and working examples to help you ship reliable integrations fast. * * * ## What is Custom Webhook? Custom Webhook is an outbound workflow action that makes an HTTP request to a URL you choose. When a workflow run reaches this step, Patient Copilot assembles your headers, parameters, and payload (including mapped dynamic values) and sends the request to the external system. * * * ## Key Benefits of Custom Webhook Understanding where Custom Webhook shines helps you pick the right automation tool and structure requests correctly for your provider. - Flexible methods: Use GET, POST, PUT, DELETE to match any API operation. - Authentication options: Bearer token, API key, Basic Auth, OAuth2, or No auth with custom headers. - Precise data mapping: Dynamic values (e.g., {{contact.email}}) populate headers, params, or body so every call includes the right record details. - Reusable patterns: Build once, reuse across workflows with consistent headers, content types, and payload shapes. - Faster troubleshooting: Optional response capture and workflow execution logs streamline testing and issue resolution. * * * ## Authentication Options External APIs often require credentials. Choose the option your provider supports and place secrets in headers—not URLs—for better security. - Bearer Token Use header Authorization: Bearer . Example header: Authorization: Bearer {{location.api_token}} - API Key Most services expect a custom header (e.g., X-API-Key: ). Only use query‑string keys if the provider requires it. Header example: X-API-Key: {{location.external_api_key}} - Query example (only if required):?api_key={{location.external_api_key}} - Basic Auth Provide Username and Password in the action’s Authorization fields. Patient Copilot sends the proper Authorization: Basic… header. - OAuth2 If your provider uses OAuth2, first configure the token in Global Workflow Settings → OAuth2 / Manage Tokens, then select it in the action. OAuth2 is recommended for providers that rotate or refresh tokens automatically. - No Auth + Custom Header If your provider asks for a bespoke header (e.g., X-Signature: ), choose No auth, then add the header under Headers. * * * ## HTTP Methods & Request Components Matching the correct method and placing data in the right part of the request prevents 400/401/422 errors and speeds up integrations. - URL & Path Parameters: You can include variables in the path, e.g., https://api.example.com/contacts/{{contact.id}}. - GET: Retrieve data. Bodies are typically ignored—use query parameters: https://api.example.com/leads?email={{contact.email}}&status=active - POST: Create resources. Send a JSON body or form data (see Content‑Type). - PUT: Update resources. Usually requires an ID in the path and a JSON body. - DELETE: Remove resources. Often includes the ID in the path. - Content‑Type: Common values: application/json (JSON body) or application/x-www-form-urlencoded (form fields). Match your provider’s docs. * * * ## Event vs Method (UI Behavior) The Custom Webhook action offers two configuration modes. CUSTOM exposes full control (method, content type, raw body). GET/POST offer simplified experiences. Pick the mode that matches your provider’s requirements. - Event = CUSTOM (advanced): - Shows Method (GET, POST, PUT, DELETE), Content-Type, and Raw Body editor for JSON or other formats. - Best when you need JSON payloads, non‑POST methods, or explicit headers/content types. - Event = POST (simple): - Shows Body (Key and Value) pairs for a form‑style payload; no Raw Body editor. - Use for simple key/value submissions. Switch to CUSTOM if your provider expects JSON. - Event = GET (simple): - No request body. Use Query Parameters for filters. Save response from this Webhook is available. - Event picker: - The Event dropdown controls which fields appear. Choose CUSTOM for full control. - Variable picker: - The small tag icon next to fields (URL, Headers, Query Params, Body) opens the dynamic value picker to insert values like {{contact.id}}. * * * APIs commonly require specific headers and query parameters for auth, content type, versioning, or filtering. Map dynamic values when needed. - Headers (examples): Authorization: Bearer {{location.api_token}} Content-Type: application/json X-API-Key: {{location.external_api_key}} X-App-Version: 2024-11-01 - Query parameters (examples): lead_id={{contact.id}} email={{contact.email}} source=workflow - Avoid putting secrets in query strings unless your provider requires it. * * * ## Payload & Field Mapping Dynamic values let you personalize each request with contact, opportunity, or other workflow data—shaped to match the external API. - Flat JSON payload (POST / create): { "id": "{{contact.id}}", "first_name": "{{contact.first_name}}", "last_name": "{{contact.last_name}}", "email": "{{contact.email}}", "phone": "{{contact.phone}}" } - Nested JSON: ``` { “contact”: { “id”: “{{contact.id}}”, “name”: “{{contact.name}}”, “phones”: [“{{contact.phone}}”], “tags”: [“{{contact.tag}}”, “new-lead”] } }