Tool Webhook Tool Integration with Novu

| Field | Static | Dynamic | Description |
| --- | --- | --- | --- |
| **Routing Mode** | `Static` | `Dynamic` | Static uses the integration URL; dynamic uses subscriber endpoints. |
| **Endpoint URL** | Required | Omit | Destination URL for static mode. |
| **HTTP Method** | Yes | Yes | Default `POST`, `PUT`, or `PATCH`. Overridable per endpoint or step. |
| **Headers** | Optional | Optional | Default request headers as a JSON object string, for example `{"Authorization":"Bearer shared-token"}`. |
| **Body** | Optional | Optional | Default JSON object string merged into every request body (see [Body merge](#body-merge)). |
| **Signing Secret** | Optional | Optional | HMAC secret for the `X-Novu-Signature` header (see [Verify signatures](#verify-x-novu-signature)). |

{
  "content": "Rendered Tool step text with {{payload}} placeholders resolved"
}

{
  "event": "novu.tool",
  "version": 1,
  "content": "Rendered Tool step text"
}

import crypto from 'crypto';

const signingSecret = process.env.NOVU_TOOL_WEBHOOK_SECRET!;

export function verifyNovuToolWebhook(rawBody: string, signatureHeader: string | undefined): boolean {
  if (!signatureHeader) {
    return false;
  }

  const expected = crypto.createHmac('sha256', signingSecret).update(rawBody, 'utf-8').digest('hex');

  if (signatureHeader.length !== expected.length) {
    return false;
  }

  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

// Express example — register before express.json()
app.post('/novu-tool-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf-8');
  const signature = req.headers['x-novu-signature'] as string | undefined;

  if (!verifyNovuToolWebhook(rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(rawBody);
  // handle payload.content, etc.
  res.status(200).json({ id: 'received' });
});

sequenceDiagram
  participant Browser
  participant CustomerBackend as Customer backend
  participant NovuAPI as Novu API
  participant CustomerWebhook as Subscriber webhook
  Browser->>CustomerBackend: callback URL (over HTTPS)
  CustomerBackend->>NovuAPI: POST /v1/channel-endpoints (secret key)
  NovuAPI-->>CustomerBackend: 201 endpoint created
  Note over NovuAPI: url and header values stored encrypted on endpoint
  Browser->>CustomerBackend: trigger workflow
  CustomerBackend->>NovuAPI: POST /v1/events/trigger
  NovuAPI->>CustomerWebhook: POST merged payload + optional signature

  </Tab>
  <Tab title="Python">
```python
import os
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.channel_endpoints.create(create_channel_endpoint_request_body={
        "type": "tool_webhook",
        "integration_identifier": "tool-webhook",
        "subscriber_id": "<SUBSCRIBER_ID>",
        "create_subscriber_if_missing": True,
        "endpoint": {
            "url": "https://customer.example.com/hooks/novu",
            "headers": {"Authorization": "Bearer subscriber-token"},
            "method": "POST",
        },
    })

novugo "github.com/novuhq/novu-go"
"github.com/novuhq/novu-go/models/components"

  </Tab>
  <Tab title="PHP">
```php
use novu;
use novu\Models\Components;

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

$sdk->channelEndpoints->create(
    createChannelEndpointRequestBody: new Components\CreateToolWebhookEndpointDto(
        type: 'tool_webhook',
        integrationIdentifier: 'tool-webhook',
        subscriberId: '<SUBSCRIBER_ID>',
        createSubscriberIfMissing: true,
        endpoint: new Components\ToolWebhookEndpointDto(
            url: 'https://customer.example.com/hooks/novu',
            headers: ['Authorization' => 'Bearer subscriber-token'],
            method: 'POST',
        ),
    ),
);

  </Tab>
  <Tab title="Java">
```java
import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

novu.channelEndpoints().create()
    .body(CreateToolWebhookEndpointDto.builder()
        .type("tool_webhook")
        .integrationIdentifier("tool-webhook")
        .subscriberId("<SUBSCRIBER_ID>")
        .createSubscriberIfMissing(true)
        .endpoint(ToolWebhookEndpointDto.builder()
            .url("https://customer.example.com/hooks/novu")
            .headers(Map.of("Authorization", "Bearer subscriber-token"))
            .method("POST")
            .build())
        .build())
    .call();

curl -L 'https://api.novu.co/v1/channel-endpoints?subscriberId=<SUBSCRIBER_ID>&integrationIdentifier=tool-webhook' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>'

  </Tab>
  <Tab title="Python">
```python
import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="ops-handoff",
        to={"subscriber_id": "<SUBSCRIBER_ID>"},
        payload={
            "incidentId": "INC-42",
            "severity": "high",
        },
    ))

novugo "github.com/novuhq/novu-go"
"github.com/novuhq/novu-go/models/components"

  </Tab>
  <Tab title="PHP">
```php
use novu;
use novu\Models\Components;

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

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'ops-handoff',
        to: new Components\SubscriberPayloadDto(subscriberId: '<SUBSCRIBER_ID>'),
        payload: [
            'incidentId' => 'INC-42',
            'severity' => 'high',
        ],
    ),
);

  </Tab>
  <Tab title="Java">
```java
import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("ops-handoff")
        .to(To2.of(SubscriberPayloadDto.builder().subscriberId("<SUBSCRIBER_ID>").build()))
        .payload(Map.of(
            "incidentId", "INC-42",
            "severity", "high"
        ))
        .build())
    .call();