Custom Channel webhook contract

Engage campaigns can target a Custom channel in addition to push, web push, SMS, and email. On this channel, Binoban makes an outbound HTTP request to an endpoint your team configures, so you can fan sends out to any delivery system of your own — an internal messaging queue, a channel Binoban doesn't natively support, and so on.

Optional, and not push

Custom Channel is only relevant if a Binoban admin on your team has configured a Custom channel provider for your workspace. It is unrelated to push and web push — most integrations never use it. For push, see App push and Web push.

This is a receiving contract, not an SDK call. There's nothing to import or initialize; your job is to stand up an HTTP endpoint that accepts what Binoban sends and returns a 2xx status.

Configured in the panel, not by API

The endpoint URL, HTTP method, headers, and body template are set by a Binoban admin on your team in the Product Workspace (Engage → Providers), not through a public API call. This page documents what your endpoint will receive once that provider is configured — coordinate the URL/headers/template with whoever configures it.

What gets configured

Field	Notes
method	One of GET, POST, PUT, DELETE.
url	Your webhook endpoint. Max 255 characters.
headers	Arbitrary key/value pairs sent on every request — this is where you put any static auth header (see Authentication below).
body	A JSON template written in {{ }} placeholders (see Template variables). Max 10,000 characters.

Request shape

• Target and method are exactly the configured url and method.
• Headers are exactly the configured key/value pairs — Binoban adds nothing else.
• Body is always a JSON array, even for a single notification. Each array element is the configured body template, rendered once per recipient in the batch and parsed as JSON. A batch of 50 recipients produces one HTTP request with a 50-element array body.

POST https://your-endpoint.example.com/binoban-engage
Content-Type: application/json
<your configured headers>

[
  { "...your template, rendered for recipient 1..." },
  { "...your template, rendered for recipient 2..." }
]

Template variables

The body template is evaluated per recipient with these placeholders available:

Placeholder	Value
{{token}}	An opaque tracking token identifying this send (notification, campaign, variation, recipient). Echo it back on any delivery/click callback you build (see Tracking below).
{{user.userId}} / {{user.anonymousId}} / {{user.profileId}}	The recipient's identifiers.
{{user.email}} / {{user.phone}} / {{user.firstName}} / {{user.lastName}} / {{user.timezone}}	Recipient profile fields.
{{campaign.id}} / {{campaign.channel}} / {{variation.id}}	Campaign/variation identifiers.
{{variation.channelData.message}}	The message body content authored in the panel.
{{variation.channelData.subject}}	Subject line, if the campaign sets one.
{{variation.channelData.image}} / {{variation.channelData.icon}}	Image/icon URLs, if set.
{{variation.channelData.propertiesArray}}	JSON string of the campaign's custom key/value properties.
{{variation.channelData.attachmentsArray}}	JSON string of any configured attachments.

String values are JSON-escaped before substitution, so it's safe to place them inside quoted JSON string fields in the template. The rendered result must be valid JSON — if a template fails to render or produces invalid JSON, that one recipient is dropped from the batch; the rest still send.

Response semantics

• Any 2xx status code is treated as success for that batch element.
• Any non-2xx status code marks that recipient's send as failed (PROVIDER_REJECTED_REQUEST); your response body is captured as the failure reason.
• A transport-level failure (timeout, connection refused, DNS failure) marks the send PROVIDER_CALL_FAILED.
• Binoban does not parse your response body for a message ID or other content beyond the status code — there's no round-trip provider-ID capture today.

Authentication

Binoban adds no authentication of its own to these requests — no signature, no HMAC, no timestamp. The only credential your endpoint can rely on is whatever static header (for example, Authorization: Bearer <your-static-token>) you configured on the provider. Treat the endpoint URL as effectively public and validate the configured header on every request.

Request signing

There is currently no built-in request-signing or replay-protection mechanism for Custom Channel webhooks. If your integration needs stronger verification than a static shared header, raise it with Binoban — this is an open product question, not a documented capability today.

Tracking

{{token}} is designed to round-trip back to Binoban so delivery/click/close events show up alongside your other Engage channels, mirroring the callback pattern push and web push use (/api/tracker/general/{delivered,click,close,failed}?token=...).

Custom-channel tracking callback

The exact callback endpoint and parameters for the Custom channel specifically have not been confirmed. If you need delivery/click tracking on Custom sends, confirm the callback contract with Binoban before building against it — don't assume the push callback shape applies unchanged.

Next steps

• App push · Web push — the SDK-side channels, if native delivery covers your use case.
• Activate Engage — what's panel-owned vs. developer-owned.
• Authentication — Binoban's own API auth model (unrelated to the static header above, which authenticates your endpoint).