Webhooks

Real-time HTTP POST notifications when events fire in your account. Register an endpoint instead of polling.

Base URL

https://api.dyva.ai/v1

Setup

POST/v1/webhooksAuth Required

Create a new webhook subscription.

Request Body

Name	Type	Required	Description
`url`	string	Required	The HTTPS endpoint that will receive webhook events.
`events`	string[]	Required	List of event types to subscribe to.
`secret`	string	Optional	Signing secret for payload verification. Auto-generated if omitted.

Response

{
  "id": "wh_f1e2d3c4b5a6",
  "url": "https://yourapp.com/webhooks/dyva",
  "events": [
    "message.created",
    "conversation.created"
  ],
  "secret": "whsec_k8j7h6g5f4d3s2a1...",
  "active": true,
  "created_at": "2026-03-09T12:00:00Z"
}

Examples

$_cURL

JSJavaScript

PyPython

curl -X POST https://api.dyva.ai/v1/webhooks \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/dyva",
    "events": ["message.created", "conversation.created"]
  }'

GET/v1/webhooksAuth Required

List all webhooks for the current account.

Response

{
  "data": [
    {
      "id": "wh_f1e2d3c4b5a6",
      "url": "https://yourapp.com/webhooks/dyva",
      "events": [
        "message.created",
        "conversation.created"
      ],
      "active": true,
      "created_at": "2026-03-09T12:00:00Z"
    },
    {
      "id": "wh_a6b5c4d3e2f1",
      "url": "https://yourapp.com/webhooks/billing",
      "events": [
        "subscription.created",
        "subscription.cancelled"
      ],
      "active": true,
      "created_at": "2026-03-08T09:15:00Z"
    }
  ],
  "total": 2
}

PUT/v1/webhooks/:idAuth Required

Update the URL or subscribed events for an existing webhook.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the webhook.

Request Body

Name	Type	Required	Description
`url`	string	Optional	Updated HTTPS endpoint.
`events`	string[]	Optional	Updated list of event types.

Response

{
  "id": "wh_f1e2d3c4b5a6",
  "url": "https://yourapp.com/webhooks/dyva-v2",
  "events": [
    "message.created",
    "message.failed",
    "conversation.created"
  ],
  "active": true,
  "created_at": "2026-03-09T12:00:00Z"
}

DELETE/v1/webhooks/:idAuth Required

Remove a webhook and stop receiving events.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the webhook.

Response

{
  "id": "wh_f1e2d3c4b5a6",
  "deleted": true
}

Events

Subscribe to any combination of these event types.

Event Type	Description
Conversations
`conversation.created`	A new conversation was started.
`conversation.deleted`	A conversation was deleted.
Messages
`message.created`	A new message was sent or received.
`message.failed`	A message failed to deliver.
Characters
`dyva.created`	A new character was created.
`dyva.updated`	A character's configuration was changed.
`dyva.deleted`	A character was deleted.
`dyva.published`	A character was published to the marketplace.
Subscriptions
`subscription.created`	A new subscription was started.
`subscription.updated`	A subscription plan was changed.
`subscription.cancelled`	A subscription was cancelled.
Integrations
`integration.connected`	A platform integration was connected.
`integration.disconnected`	A platform integration was disconnected.
`integration.error`	A platform integration encountered an error.

Payload Format

Every delivery sends a JSON payload with a standard envelope. The data object varies by event type.

Field	Type	Description
`id`	string	Unique event identifier. Use this for deduplication.
`type`	string	The event type, e.g. "message.created".
`created_at`	string	ISO 8601 timestamp of when the event occurred.
`data`	object	Event-specific payload containing the relevant resource.

Example payload

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "message.created",
  "created_at": "2026-03-09T14:22:31Z",
  "data": {
    "conversation_id": "conv_x9y8z7w6",
    "message_id": "msg_m4n5o6p7",
    "role": "user",
    "content": "Hello, how does this work?",
    "dyva_id": "rp_7k9m2x4v"
  }
}

Signature Verification

Every request includes an X-Dyva-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret. Always verify before processing.

Node.js

PyPython

import crypto from "crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

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

// In your request handler
app.post("/webhooks/dyva", (req, res) => {
  const signature = req.headers["x-dyva-signature"];
  const rawBody = req.body; // raw string, not parsed JSON

  if (!verifyWebhook(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(rawBody);
  // Process the event...

  res.status(200).send("ok");
});

Retry Policy

No 2xx response within 5 seconds triggers retries with exponential backoff.

Attempt	Delay
1st retry	10 seconds
2nd retry	60 seconds
3rd retry	300 seconds (5 minutes)

After 3 failed retries, the event is marked failed. 100 consecutive failures disables the webhook automatically. Re-enable it via the API once your endpoint is healthy.

Best Practices

•Respond with 2xx quickly. Return 200 immediately. Defer heavy processing to a background job to avoid the 5-second timeout.
•Process events asynchronously. Enqueue the payload and process it outside the request lifecycle.
•Verify signatures on every request. Always check X-Dyva-Signature before trusting the payload.
•Handle duplicate deliveries. Use the event id for idempotency. Storefront processed IDs and skip duplicates.
•HTTPS only. Plaintext HTTP endpoints are rejected.
•Monitor delivery health. Track failure rates. Fix issues before hitting the 100-failure disable threshold.

Authentication

Embedding

Webhooks

Real-time HTTP POST notifications when events fire in your account. Register an endpoint instead of polling.

Base URL

https://api.dyva.ai/v1

Setup

POST/v1/webhooksAuth Required

Create a new webhook subscription.

Request Body

Name	Type	Required	Description
`url`	string	Required	The HTTPS endpoint that will receive webhook events.
`events`	string[]	Required	List of event types to subscribe to.
`secret`	string	Optional	Signing secret for payload verification. Auto-generated if omitted.

Response

{
  "id": "wh_f1e2d3c4b5a6",
  "url": "https://yourapp.com/webhooks/dyva",
  "events": [
    "message.created",
    "conversation.created"
  ],
  "secret": "whsec_k8j7h6g5f4d3s2a1...",
  "active": true,
  "created_at": "2026-03-09T12:00:00Z"
}

Examples

$_cURL

JSJavaScript

PyPython

curl -X POST https://api.dyva.ai/v1/webhooks \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/dyva",
    "events": ["message.created", "conversation.created"]
  }'

GET/v1/webhooksAuth Required

List all webhooks for the current account.

Response

{
  "data": [
    {
      "id": "wh_f1e2d3c4b5a6",
      "url": "https://yourapp.com/webhooks/dyva",
      "events": [
        "message.created",
        "conversation.created"
      ],
      "active": true,
      "created_at": "2026-03-09T12:00:00Z"
    },
    {
      "id": "wh_a6b5c4d3e2f1",
      "url": "https://yourapp.com/webhooks/billing",
      "events": [
        "subscription.created",
        "subscription.cancelled"
      ],
      "active": true,
      "created_at": "2026-03-08T09:15:00Z"
    }
  ],
  "total": 2
}

PUT/v1/webhooks/:idAuth Required

Update the URL or subscribed events for an existing webhook.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the webhook.

Request Body

Name	Type	Required	Description
`url`	string	Optional	Updated HTTPS endpoint.
`events`	string[]	Optional	Updated list of event types.

Response

{
  "id": "wh_f1e2d3c4b5a6",
  "url": "https://yourapp.com/webhooks/dyva-v2",
  "events": [
    "message.created",
    "message.failed",
    "conversation.created"
  ],
  "active": true,
  "created_at": "2026-03-09T12:00:00Z"
}

DELETE/v1/webhooks/:idAuth Required

Remove a webhook and stop receiving events.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the webhook.

Response

{
  "id": "wh_f1e2d3c4b5a6",
  "deleted": true
}

Events

Subscribe to any combination of these event types.

Event Type	Description
Conversations
`conversation.created`	A new conversation was started.
`conversation.deleted`	A conversation was deleted.
Messages
`message.created`	A new message was sent or received.
`message.failed`	A message failed to deliver.
Characters
`dyva.created`	A new character was created.
`dyva.updated`	A character's configuration was changed.
`dyva.deleted`	A character was deleted.
`dyva.published`	A character was published to the marketplace.
Subscriptions
`subscription.created`	A new subscription was started.
`subscription.updated`	A subscription plan was changed.
`subscription.cancelled`	A subscription was cancelled.
Integrations
`integration.connected`	A platform integration was connected.
`integration.disconnected`	A platform integration was disconnected.
`integration.error`	A platform integration encountered an error.

Payload Format

Every delivery sends a JSON payload with a standard envelope. The data object varies by event type.

Field	Type	Description
`id`	string	Unique event identifier. Use this for deduplication.
`type`	string	The event type, e.g. "message.created".
`created_at`	string	ISO 8601 timestamp of when the event occurred.
`data`	object	Event-specific payload containing the relevant resource.

Example payload

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "message.created",
  "created_at": "2026-03-09T14:22:31Z",
  "data": {
    "conversation_id": "conv_x9y8z7w6",
    "message_id": "msg_m4n5o6p7",
    "role": "user",
    "content": "Hello, how does this work?",
    "dyva_id": "rp_7k9m2x4v"
  }
}

Signature Verification

Every request includes an X-Dyva-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret. Always verify before processing.

Node.js

PyPython

import crypto from "crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

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

// In your request handler
app.post("/webhooks/dyva", (req, res) => {
  const signature = req.headers["x-dyva-signature"];
  const rawBody = req.body; // raw string, not parsed JSON

  if (!verifyWebhook(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(rawBody);
  // Process the event...

  res.status(200).send("ok");
});

Retry Policy

No 2xx response within 5 seconds triggers retries with exponential backoff.

Attempt	Delay
1st retry	10 seconds
2nd retry	60 seconds
3rd retry	300 seconds (5 minutes)

After 3 failed retries, the event is marked failed. 100 consecutive failures disables the webhook automatically. Re-enable it via the API once your endpoint is healthy.

Best Practices

•Respond with 2xx quickly. Return 200 immediately. Defer heavy processing to a background job to avoid the 5-second timeout.
•Process events asynchronously. Enqueue the payload and process it outside the request lifecycle.
•Verify signatures on every request. Always check X-Dyva-Signature before trusting the payload.
•Handle duplicate deliveries. Use the event id for idempotency. Storefront processed IDs and skip duplicates.
•HTTPS only. Plaintext HTTP endpoints are rejected.
•Monitor delivery health. Track failure rates. Fix issues before hitting the 100-failure disable threshold.

Authentication

Embedding

Webhooks

Setup

POST /v1/webhooks

Request Body

Response

Examples

GET /v1/webhooks

Response

PUT /v1/webhooks/:id

Path Parameters

Request Body

Response

DELETE /v1/webhooks/:id

Path Parameters

Response

Events

Payload Format

Example payload

Signature Verification

Retry Policy

Best Practices

Webhooks

Setup

POST /v1/webhooks

Request Body

Response

Examples

GET /v1/webhooks

Response

PUT /v1/webhooks/:id

Path Parameters

Request Body

Response

DELETE /v1/webhooks/:id

Path Parameters

Response

Events

Payload Format

Example payload

Signature Verification

Retry Policy

Best Practices