> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect External Services with Webhooks

> Generic webhook integration patterns for connecting Hiveku to any service with webhook support

Most SaaS tools support incoming and outgoing webhooks. Combined with Hiveku Workflows, that's a universal adapter — you can integrate with almost anything, even services not in our native integration list.

<Info>
  If your target service is popular (Stripe, HubSpot, Slack), check for a native integration first. Webhooks are the fallback for everything else.
</Info>

## Two Directions

<CardGroup cols={2}>
  <Card title="Inbound" icon="arrow-down-to-line">
    External service sends data TO Hiveku
  </Card>

  <Card title="Outbound" icon="arrow-up-from-line">
    Hiveku sends data TO external service
  </Card>
</CardGroup>

## Common Use Cases

* **Stripe → Hiveku** — payment events create CRM records, trigger onboarding emails
* **Typeform / ConvertKit / Calendly → Hiveku** — form submissions, newsletter signups, booking confirmations
* **Hiveku → Discord / Telegram** — community pings when internal events fire
* **Hiveku → your own internal API** — sync data into legacy systems you control

## Inbound Webhook Pattern

External service fires an event, Hiveku receives and processes it.

<Steps>
  <Step title="Create a workflow with a Webhook trigger">
    **Workflows > New Workflow**. Add **Webhook trigger**. Copy the generated URL — this is your endpoint.
  </Step>

  <Step title="Register the URL with the external service">
    In the external service's settings, find the **Webhooks** section. Paste your Hiveku webhook URL as the endpoint.
  </Step>

  <Step title="Choose events to subscribe to">
    Most services let you pick specific event types — `charge.succeeded`, `form.submitted`, `booking.created`. Only subscribe to events you'll actually process; noise slows down debugging.
  </Step>

  <Step title="Save — external service sends a test event">
    Most services fire a test payload when you register a new webhook, to verify the URL works. Hiveku's webhook trigger responds 200 on any valid POST, so the test should pass.
  </Step>

  <Step title="Handle the event">
    Add downstream actions in your workflow to process the event: send email, update database, call another API.
  </Step>

  <Step title="Inspect the first real payload">
    Open **Workflows > your workflow > Runs** and check the trigger data from the first real event. Use the actual field names there when building downstream steps.
  </Step>
</Steps>

## Outbound Webhook Pattern

Hiveku fires the event, external service receives.

<Steps>
  <Step title="Get the target URL">
    From the receiving service's docs. Usually labeled "webhook URL" or "incoming webhook endpoint".
  </Step>

  <Step title="Add an HTTP Request action">
    In your Hiveku workflow, click **+ Add Action > HTTP Request**:

    * **Method:** usually POST (some services require PUT — check docs)
    * **URL:** the target URL
    * **Headers:**

      ```
      Content-Type: application/json
      Authorization: Bearer {{env.EXTERNAL_API_KEY}}
      ```
    * **Body:** JSON matching the receiving API's spec

    ```json theme={null}
    {
      "event": "new_signup",
      "user": {
        "email": "{{trigger.email}}",
        "name": "{{trigger.name}}"
      }
    }
    ```
  </Step>

  <Step title="Test with the service's sandbox">
    Many services offer a test mode or sandbox endpoint. Use that before flipping to production URL.
  </Step>
</Steps>

## Securing Inbound Webhooks

Public webhook endpoints are open to the internet. Without verification, anyone who discovers the URL can forge events.

<Warning>
  Treat webhook URLs like API keys. Don't commit them to public repos or share in screenshots.
</Warning>

**HMAC signature verification** is the gold standard. Most reputable services (Stripe, GitHub, Shopify) sign outgoing webhook payloads with a shared secret. Verify the signature before processing:

1. The service sends the signature in a header (e.g., `Stripe-Signature`, `X-Hub-Signature-256`).
2. Your workflow reads the raw request body and the header.
3. Compute HMAC-SHA256(body, shared\_secret) and compare to the header value.
4. Reject requests with mismatched signatures.

Hiveku's Webhook trigger exposes both the parsed body and the raw body via `{{trigger.raw}}` for this purpose. Add a **Verify Signature** step or a custom Code step before downstream actions.

**URL rotation** is the fallback when signature verification isn't available. If a webhook URL leaks, delete the trigger and create a new one — all old URLs stop working immediately.

## Handling Failures

Webhooks are fire-and-forget. Neither side is guaranteed to process every message without error.

* **External services retry on 5xx responses.** Return 200 as fast as possible — within 3 seconds is the informal standard — then process async if needed. For long-running work, drop the event into a queue and acknowledge immediately.
* **For outgoing webhooks, Hiveku retries with exponential backoff** when the receiver returns 5xx or times out. Check the workflow's **Runs** tab for retry attempts.
* **Add a failure alert** to your workflow so broken integrations don't silently drop events. A Slack action configured with **Send on failure** is the lightest-weight option.

<Tip>
  Most complex integrations can be built with 2-3 webhook-connected workflows. If you find yourself chaining six or seven, consider opening a native integration request — the engineering team can often prioritize common patterns.
</Tip>

## Testing Webhooks Locally

When you're debugging payload formats or signature verification:

* **webhook.site** — free tool that catches any POST and shows the full payload. Paste your workflow URL into the external service temporarily, fire an event, and inspect what's actually sent.
* **ngrok** — tunnels your local development server to a public URL. Useful when building custom webhook handlers outside of Hiveku.
* **Run the workflow manually** — in Hiveku, click **Run Now** with a custom payload. Lets you iterate on downstream actions without waiting for real events.

Always test in staging before enabling on production. A misconfigured outbound webhook that blasts real customer data to the wrong URL is a rough day.

## Verify It Worked

Fire a real event from the external service. Confirm:

1. The Hiveku workflow's **Runs** tab shows the event with the expected payload
2. Downstream actions completed without errors
3. For outbound webhooks, the receiving service logs show the event arrived
4. Retries and failures (if any) are being reported to your chosen alert channel

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook isn't triggering">
    Check the obvious causes first: URL typo, external service expecting a different HTTP method (some want POST, others PUT), workflow not enabled. If the external service has a "recent deliveries" log, it'll tell you whether the request was attempted at all.
  </Accordion>

  <Accordion title="Signature verification is failing">
    Use the raw request body for HMAC, not the parsed JSON. Parsing and re-serializing changes whitespace and key order, which breaks the signature. Hiveku exposes `{{trigger.raw}}` for this. Also check the secret — leading/trailing whitespace is a classic cause of silent mismatches.
  </Accordion>

  <Accordion title="Payload format is different from what I expected">
    External service docs sometimes lag behind actual behavior. Log the first real payload (via webhook.site or a Hiveku Code step that writes to a table) and build against that. Don't trust the docs as the source of truth for field names.
  </Accordion>

  <Accordion title="Outbound webhook returns 403 or 401">
    Authentication header is wrong. Check the external service's API docs for the exact format — some want `Authorization: Bearer <key>`, others want `X-API-Key: <key>`, others use Basic Auth. Copy the example from their curl snippet exactly.
  </Accordion>

  <Accordion title="Rate limits are kicking in">
    The receiver is limiting how many requests/sec you can send. Add a **Delay** action between requests, batch events into a single call, or contact the service for a higher rate limit. If it's inbound, acknowledge fast and process async.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Workflows Basics" icon="diagram-project" href="/how-tos/workflows">
    Triggers, actions, and run history explained
  </Card>

  <Card title="Connect Zapier" icon="bolt" href="/how-tos/connect-zapier">
    Use Zapier as a universal bridge to 6,000+ apps
  </Card>
</CardGroup>