Campaign Status Update

Sent when a campaign is created or its status changes. Whenever a campaign is booked, paused, closed, or otherwise changes state, Kini POSTs a payload to the URL you configure.

Overview

Sent when a campaign is booked (created) and every time its status changes afterwards — for example when it is paused, needs action, or ends. Use it to keep your system in sync with the lifecycle of each campaign, such as Bundesagentur für Arbeit campaigns booked by your customers.

An event is only sent on an actual status transition. Saving a campaign without changing its status does not send a webhook.

Events

Event	Sent when
`campaign_created`	A campaign was booked.
`campaign_status_active`	The campaign became active, e.g. after being reactivated or fixed.
`campaign_status_action_required`	At least one job in the campaign is missing data required by the job board.
`campaign_status_paused`	The campaign was paused.
`campaign_status_closed`	The campaign was closed by the customer before its end date.
`campaign_status_completed`	The campaign ran until its end and was completed.
`campaign_status_deleted`	A draft campaign was deleted.

All events share the same payload. The payload is loaded when the webhook is delivered, so campaign_status contains the campaign's status at delivery time. Use the event name to tell which transition happened.

Payload

The following payload is sent to your configured webhook URL:

{
  "company_id": 123,
  "company_name": "Test GmbH",
  "partner_company_id": "1019261",
  "campaign_id": 4711,
  "campaign_name": "Pflegekräfte Q4",
  "campaign_status": "paused",
  "campaign_starts_at": "2026-10-01T00:00:00Z",
  "campaign_ends_at": "2026-12-31T00:00:00Z",
  "product_id": 3040,
  "product_name": "Bundesagentur für Arbeit",
  "transaction_id": "ffdc0e8c-2653-4589-96bb-fef46e9fb520"
}

Field Name	Type	Description
`company_id`	int	The unique Kini ID of the company.
`company_name`	string	The name of the company.
`partner_company_id`	string	The partner-specific ID of the company, in case it was provided upon company onboarding.
`campaign_id`	int	The unique Kini ID of the campaign.
`campaign_name`	string	The name of the campaign.
`campaign_status`	enum	The current status of the campaign (see Status Values).
`campaign_starts_at`	datetime	ISO 8601 start of the campaign, or `null` if not set.
`campaign_ends_at`	datetime	ISO 8601 end of the campaign, or `null` if not set.
`product_id`	int	The unique Kini ID of the booked product.
`product_name`	string	The name of the booked product.
`transaction_id`	uuid	The unique transaction ID associated with the campaign booking.

Status Values

The campaign_status field can have the following values:

draft: The campaign was created but not booked yet. No status event is sent for this status.
active: The campaign is live and its jobs are being published.
action_required: The campaign is live, but at least one job could not be published because required data is missing.
paused: The campaign was paused. Its jobs are taken offline until it is reactivated.
closed: The campaign was ended early by the customer. Its jobs are unpublished.
completed: The campaign ran until its end. Its jobs have expired.
deleted: The draft campaign was deleted.

Delivery & Retries

Deliveries are sent as an HTTPS POST with a JSON body and a 20-second timeout. If your endpoint returns a retryable status (429, 500, 502, 503, 504) or the connection times out, Kini makes up to 3 attempts in total, waiting roughly 1s and then 2s between them. Any other non-2xx response is treated as a permanent failure and is not retried.

A single action can cause more than one event. For example, reactivating a paused campaign sends campaign_status_active and, if a job is still missing required data, campaign_status_action_required right after. Because the payload is loaded at delivery time, both deliveries can then contain "campaign_status": "action_required".

Authentication

Kini calls your endpoint, so authentication is under your control: when your webhook is set up, you tell us which HTTP headers each delivery should carry — for example an Authorization: Bearer {token} header or a custom API-key header that your endpoint checks. Kini stores these securely and sends them with every request.

Setup

Campaign events can be delivered for a single company or for all companies of a partner. Contact tech@getkini.com with the HTTPS URL that should receive events, the headers Kini should send, and which of the events above you want to receive.

Was this page helpful?