Custom Payloads

By default, Aktify sends events using the standard request format. If your integration expects a different structure, you can define a custom payload that overrides the default request body for specific event types.

V2 events only

Custom payloads apply only to V2 webhook events. Legacy v1 events always use the default v1 request format.

Custom payloads are completely optional. To configure them, open Settings → Webhooks and click Custom Payloads, then click Create Custom Payload.

Each event type can have only one custom payload configuration. Event types without a custom payload continue to use the default format.

Custom payloads are not signed

The aktify-signature header is not sent for requests that use a custom payload. Signature verification is unavailable for these requests — use a custom authentication header (see below) if you need to authenticate the request instead.

Configuring a custom payload

• Event type — The V2 event this configuration applies to. Each event type supports a single custom payload.
• Request Template — The body Aktify sends for this event. Use {{ fieldName }} placeholders to insert event data. Injected values are not wrapped in quotes, so add quotes in your template where you need string values (for example, { "phone": "{{ phone }}" }). When a field's value is null, an empty string is inserted. Leave the template empty to keep the default payload while still applying your custom headers and authentication.
• Content Type — The Content-Type header for the request. Leave empty to use the default, application/json.
• Custom Headers — A JSON object of additional headers to send, for example {"header-key": "header-value"}.
• Authentication — Choose None, Basic Auth (username and password), or Bearer Token. Aktify adds the corresponding Authorization header to each request.

Template variables

Every event type can reference these built-in values:

Placeholder	Description
{{ eventType }}	The event type name
{{ eventTime }}	ISO 8601 timestamp of when the event occurred
{{ campaignId }}	The campaign ID associated with the event

In addition, you can reference any field from that event's data payload — for example {{ phone }}, {{ message }}, or {{ externalLeadId }}. See the individual V2 event pages for the fields available on each event. The Portal highlights known fields as you type and flags placeholders that don't exist for the selected event.

Example

A custom payload template for lead.message_sent that sends a flat, unsigned JSON body:

{
  "event": "{{ eventType }}",
  "campaign": "{{ campaignId }}",
  "phone": "{{ phone }}",
  "message": "{{ message }}",
  "occurredAt": "{{ eventTime }}"
}