Connect a Custom Channel (webhook-based)

The Custom Channel (listed in the type picker as Custom Channel) is the escape hatch for connecting any in-house or legacy system Omnifox doesn't natively support — an internal CRM, a proprietary chat, a bespoke ticketing system. It works with two URLs: one Omnifox gives you to receive messages, and one you provide so Omnifox can send outbound messages to your system.

Requirements

• An external system able to receive HTTP POST requests with JSON and expose its own endpoint
• A descriptive name for the channel (e.g. "Internal CRM" or "Legacy System")

Steps to connect

1. In Omnifox, go to Channels → Connect New Channel and pick Custom Channel.
2. Save the channel so Omnifox generates the Incoming Webhook URL and a Secret Key (both read-only, with a copy button).
3. Fill in the Outgoing Webhook URL: the address on your system where Omnifox will send outbound messages.
4. Configure your external system to POST inbound messages (JSON) to Omnifox's Incoming Webhook URL.
5. Optional: set up Field Mappings (see the dedicated field-mapping article) if your payload doesn't use the default field names.

Configuration

• Incoming Webhook URL: receives JSON from your system; used to create inbound messages in the Inbox.
• Outgoing Webhook URL: where Omnifox POSTs when an agent replies.
• Secret Key: signs every outbound request with HMAC-SHA256 (X-Omnifox-Signature, X-Omnifox-Timestamp, X-Omnifox-Channel-Type, X-Omnifox-Delivery headers).

Example

An internal ticketing system receives a support request and POSTs it to Omnifox's webhook as {"text": "I need help", "sender": "John", "id": "tk_123"}. That message shows up in the Inbox; when an agent replies, Omnifox POSTs to your Outgoing Webhook URL with the default body (message_id, conversation_id, recipient, content, etc.).

Tips

• Always verify the HMAC signature on your system's side before processing a request — this stops third parties from injecting fake messages.
• If your system returns a 4xx, Omnifox treats it as fatal (no retry); on a 5xx or timeout it retries up to 3 times with backoff.

Troubleshooting

• Outbound messages never arrive: check that your Outgoing Webhook URL responds with 2xx within 30 seconds.
• Inbound messages don't show up in the Inbox: confirm you're posting to the exact Incoming Webhook URL Omnifox gave you, with Content-Type application/json.