Skip to main content
POST
/
v1
/
events
/
trigger
PHP
declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity(
        'YOUR_SECRET_KEY_HERE'
    )
    ->build();

$triggerEventRequestDto = new Components\TriggerEventRequestDto(
    workflowId: 'workflow_identifier',
    payload: [
        'comment_id' => 'string',
        'post' => [
            'text' => 'string',
        ],
    ],
    overrides: new Components\Overrides(),
    to: 'SUBSCRIBER_ID',
    actor: '<value>',
    context: [
        'key' => 'org-acme',
    ],
);

$response = $sdk->trigger(
    triggerEventRequestDto: $triggerEventRequestDto
);

if ($response->triggerEventResponseDto !== null) {
    // handle response
}
{
  "acknowledged": true,
  "error": [
    "<string>"
  ],
  "transactionId": "<string>",
  "activityFeedLink": "<string>",
  "jobData": {}
}
Trigger a workflow by sending a POST request with the workflow identifier, target subscriber(s), and optional payload. The response includes a transactionId you can use to trace the run in the Activity Feed, cancel the event, or look up related messages.

​
Idempotency and billing

If you retry a trigger request, use an idempotency key to avoid duplicate workflow runs and duplicate billing.
MechanismWhere it appliesEffect on billing
Idempotency-Key headerAPI layer, before the request is queuedAfter the first request completes, duplicates return the cached response and count as one workflow run
transactionId in the request bodyDuring trigger processingDoes not provide the same API-level protection as an idempotency key
When you send the same Idempotency-Key on multiple POST /v1/events/trigger requests, Novu halts duplicates at the API layer. Once the first request completes, later requests return the cached response and never reach the worker queue, so only one trigger counts toward billing. While the first request is still processing, duplicates receive a 409 Conflict response. The optional transactionId field is useful for tracing and cancellation, but it is not a substitute for idempotency. Novu checks transactionId uniqueness during processing rather than at the API boundary, so concurrent or retried requests with the same transactionId are not deduplicated the same way. For safe retries and atomic deduplication, send an Idempotency-Key header on every trigger request.
Idempotency is not enabled for all organizations. Contact support to enable it for your organization.

Authorizations

​
Authorization
string
header
required

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

Headers

​
idempotency-key
string

A header for idempotency purposes

Body

application/json
​
name
string
required

The trigger identifier of the workflow you wish to send. This identifier can be found on the workflow page.

Example:

"workflow_identifier"

​
to
required

The recipients list of people who will receive the notification. Maximum number of recipients can be 100.

​
payload
object

The payload object is used to pass additional custom information that could be used to render the workflow, or perform routing rules based on it. This data will also be available when fetching the notifications feed from the API to display certain parts of the UI.

Example:
{
  "comment_id": "string",
  "post": { "text": "string" }
}
​
overrides
object

This could be used to override provider specific configurations

​
transactionId
string

A unique identifier for deduplication. If the same transactionId is sent again, the trigger is ignored. Useful to prevent duplicate notifications. The retention period depends on your billing tier.

​
actor

It is used to display the Avatar of the provided actor's subscriber id or actor object. If a new actor object is provided, we will create a new subscriber in our system

​
tenant

It is used to specify a tenant context during trigger event. Existing tenants will be updated with the provided details.

​
context
object

Response

Created

​
acknowledged
boolean
required

Indicates whether the trigger was acknowledged or not

​
status
enum<string>
required

Status of the trigger

Available options:
error,
trigger_not_active,
no_workflow_active_steps_defined,
no_workflow_steps_defined,
processed,
no_tenant_found,
invalid_recipients
​
error
string[]

In case of an error, this field will contain the error message(s)

​
transactionId
string

The returned transaction ID of the trigger

​
activityFeedLink
string

Link to the activity feed for this trigger event

​
jobData
object