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

# Send and Receive Real-Time Data with Fliqr AI Webhooks

> Use outbound webhooks to receive real-time Fliqr AI events on your server, and the REST API to trigger actions in Fliqr AI from external systems.

Webhooks give you a direct, low-latency channel between Fliqr AI and your own infrastructure. When something happens in Fliqr AI — a new message arrives, a flow completes, an order is placed — Fliqr AI sends an HTTP POST to an endpoint you control. Your server receives the event in real time and can respond however your application requires. The reverse also works: your server can call the Fliqr AI REST API to trigger actions (send a message, enroll a contact in a flow, update a field) from outside the platform.

## Overview

There are two directions to understand:

* **Outbound webhooks** — Fliqr AI pushes event data to your server.
* **Inbound API calls** — Your server calls Fliqr AI's REST API to take action.

Webhooks are the right choice when you need real-time data, high event volume, or tight integration with your own application logic. For simpler, low-volume automation with no-code tooling, see [Zapier & Make](/docs/integrations/zapier-make).

## Prerequisites

* A Fliqr AI account (Pro plan or higher)
* A publicly accessible HTTPS endpoint on your server to receive events
* Your Fliqr AI API key and webhook secret, both available at **Settings → API**

## Outbound Webhooks

### Supported Events

| Event                  | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `new_message`          | An inbound message was received from a contact |
| `new_contact`          | A new contact record was created               |
| `flow_completed`       | A contact reached the final block of a flow    |
| `tag_applied`          | A tag was added to a contact                   |
| `order_placed`         | A contact completed an order                   |
| `order_status_changed` | An order's status was updated                  |
| `handover_requested`   | A contact requested transfer to a live agent   |

### Registering an Outbound Webhook

<Steps>
  <Step title="Navigate to Webhooks settings">
    Go to **Settings → Webhooks → Add Webhook**.
  </Step>

  <Step title="Enter your endpoint URL">
    Paste the full HTTPS URL of the endpoint on your server that will receive events. HTTP endpoints are not accepted.
  </Step>

  <Step title="Select events">
    Check the events you want Fliqr AI to send to this endpoint. You can register multiple webhooks with different event selections if you want to route events to different endpoints.
  </Step>

  <Step title="Save and verify">
    Click **Save**. Fliqr AI sends a verification request (a POST with a `challenge` field) to your endpoint. Your endpoint must respond with the challenge value and a `200` status code to confirm the registration.

    \[SCREENSHOT: Webhooks settings panel with endpoint URL field, event checkboxes, and a verified status badge]
  </Step>
</Steps>

### Webhook Payload Example

```json theme={null}
{
  "event": "new_message",
  "timestamp": "2025-01-15T10:30:00Z",
  "contact_id": "cid_abc123",
  "channel": "whatsapp",
  "message": {
    "id": "msg_xyz789",
    "text": "Hello, I need help with my order.",
    "direction": "inbound"
  }
}
```

All timestamps are in UTC ISO 8601 format. The `contact_id` can be used to fetch or update the contact record via the REST API.

### Retry Policy

If your endpoint returns a non-`2xx` status code or doesn't respond within 10 seconds, Fliqr AI retries the delivery with exponential backoff:

| Attempt     | Delay after previous |
| ----------- | -------------------- |
| 1 (initial) | —                    |
| 2           | 30 seconds           |
| 3           | 1 minute             |
| 4           | 2 minutes            |
| 5           | 4 minutes            |
| 6 (final)   | 8 minutes            |

After 5 retries (6 total attempts), the event is dropped and logged as a failed delivery. You can review failed deliveries in **Settings → Logs → Delivery**.

## Verifying Webhook Signatures

Every outbound webhook request includes an `X-Fliqr-Signature` header. The value is an HMAC-SHA256 hash of the raw request body, signed with your webhook secret. Verifying this header confirms the request came from Fliqr AI and wasn't tampered with in transit.

<Warning>
  Always verify the webhook signature before processing the payload. Skipping this step means your endpoint will trust any POST request from anyone — webhooks can be spoofed.
</Warning>

```javascript webhook-verification.js theme={null}
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

Your webhook secret is available at **Settings → API → Webhook Secret**. If you suspect it has been compromised, rotate it from the same page — any existing endpoint registrations will start using the new secret immediately.

## Calling Fliqr AI from Your Server (Inbound API)

Your server can call the Fliqr AI REST API at any time to trigger actions. Authenticate every request with a Bearer token using your API key:

```http theme={null}
POST https://api.fliqr.ai/v1/contacts/{contact_id}/flows
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "flow_id": "flow_abc123"
}
```

Refer to the [API Reference](/docs/api-reference/authentication) for the full endpoint list.

## External Request Block in Flows

You don't have to call external APIs only from your server. Inside any flow in the Flow Builder, you can add an **External Request** block to make an HTTP call to any endpoint mid-conversation.

* Supported methods: GET, POST, PUT, DELETE
* Add headers (including Authorization headers for authenticated APIs)
* Pass dynamic values from the current contact's custom fields in the request body
* Map fields from the JSON response back to contact custom fields, making them available in subsequent blocks

This lets a flow look up a customer's order status from your own backend and then respond with the result — all without leaving the Flow Builder.

<Tip>
  Use the External Request block for lightweight, per-contact lookups. For bulk operations or event-driven workflows that don't involve a single conversation, use outbound webhooks and your own backend logic.
</Tip>

## What's Next

<CardGroup cols={2}>
  <Card title="API Authentication" href="/docs/api-reference/authentication">
    Learn how to authenticate REST API requests and manage API keys.
  </Card>

  <Card title="Zapier & Make" href="/docs/integrations/zapier-make">
    Use no-code automation platforms to connect Fliqr AI to external apps.
  </Card>
</CardGroup>