Set Webhook

Auth: TokenAccount or TokenInstance • Rate limit: Global (100/min) • Idempotent: yes (upsert by label)

Description

Creates or updates the (instance, label) row in webhook_configs. Each instance accepts up to 3 simultaneously enabled webhooks, identified by a free-form label. Webhooks with enabled=false are kept in the database but do not count toward the limit and do not receive deliveries. Use cases:

Create a new webhook: send a label not used yet.
Update existing: send the same label, all new fields overwrite the old ones.
Soft-disable: send the same label with {"enabled": false} (clears url, authorization, events, mediaBase64, but preserves the row).
Parallel migration: run the old webhook while validating the new one under a different label; once confirmed, disable the old one.

Examples

Minimum

Enables the default webhook pointing to https://meuapp.com/webhook. Without events, it receives the 6 types; without authorization, it sends no auth header.

curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url":     "https://meuapp.com/webhook"
  }'

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    enabled: true,
    url:     "https://meuapp.com/webhook"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "enabled": True,
        "url":     "https://meuapp.com/webhook"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "enabled": true,
        "url":     "https://meuapp.com/webhook"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

With label, filter and Authorization

Creates a webhook named analytics-pipeline that only receives message.exchange and message.status, sends the header Authorization: Bearer svc-token-xyz on each delivery, and turns off the base64 backup.

curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":         "analytics-pipeline",
    "enabled":       true,
    "url":           "https://analytics.meuapp.com/events",
    "authorization": "Bearer svc-token-xyz",
    "events":        ["message.exchange", "message.status"],
    "mediaBase64":   false
  }'

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    label:         "analytics-pipeline",
    enabled:       true,
    url:           "https://analytics.meuapp.com/events",
    authorization: "Bearer svc-token-xyz",
    events:        ["message.exchange", "message.status"],
    mediaBase64:   false
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "label":         "analytics-pipeline",
        "enabled":       True,
        "url":           "https://analytics.meuapp.com/events",
        "authorization": "Bearer svc-token-xyz",
        "events":        ["message.exchange", "message.status"],
        "mediaBase64":   False
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "label":         "analytics-pipeline",
        "enabled":       true,
        "url":           "https://analytics.meuapp.com/events",
        "authorization": "Bearer svc-token-xyz",
        "events":        ["message.exchange", "message.status"],
        "mediaBase64":   false
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

byEvents = true (URL-based routing)

Turns on byEvents: true so each delivery is sent with the event name as a URL suffix (e.g., https://meuapp.com/wh/message.exchange), allowing server-side routing per endpoint without inspecting the payload.

curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":    "router",
    "enabled":  true,
    "url":      "https://meuapp.com/wh",
    "byEvents": true,
    "events":   []
  }'
# Deliveries go to https://meuapp.com/wh/message.exchange, /group.flow, ...

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    label:    "router",
    enabled:  true,
    url:      "https://meuapp.com/wh",
    byEvents: true,
    events:   []
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "label":    "router",
        "enabled":  True,
        "url":      "https://meuapp.com/wh",
        "byEvents": True,
        "events":   []
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "label":    "router",
        "enabled":  true,
        "url":      "https://meuapp.com/wh",
        "byEvents": true,
        "events":   []
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Soft-disable preserving the label

Disables the analytics-pipeline webhook by sending only enabled: false. The row stays in the database but url, authorization, events and mediaBase64 are cleared, and the entry no longer counts toward the limit of 3 active webhooks.

curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":   "analytics-pipeline",
    "enabled": false
  }'

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    label:   "analytics-pipeline",
    enabled: false
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "label":   "analytics-pipeline",
        "enabled": False
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "label":   "analytics-pipeline",
        "enabled": false
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Base64 media (raw backup)

Configures a webhook dedicated to backup that only receives message.exchange with mediaBase64: true, so each message with media includes the binary content base64-encoded inside the payload.

curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label":       "backup-raw",
    "enabled":     true,
    "url":         "https://backup.meuapp.com/raw",
    "events":      ["message.exchange"],
    "mediaBase64": true
  }'

await fetch(`https://ryzeapi.cloud/api/events/webhook/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    label:       "backup-raw",
    enabled:     true,
    url:         "https://backup.meuapp.com/raw",
    events:      ["message.exchange"],
    mediaBase64: true
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/events/webhook/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "label":       "backup-raw",
        "enabled":     True,
        "url":         "https://backup.meuapp.com/raw",
        "events":      ["message.exchange"],
        "mediaBase64": True
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "label":       "backup-raw",
        "enabled":     true,
        "url":         "https://backup.meuapp.com/raw",
        "events":      ["message.exchange"],
        "mediaBase64": true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/events/webhook/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Success response

The response returns the webhook object with the configuration actually persisted (label, enabled, url, authorization, byEvents, events, mediaBase64), mirrors the request body after the upsert. When enabled=false, the url, authorization, events and mediaBase64 fields come back cleared. The dispatcher starts using the new config immediately (the internal 30s cache is invalidated on save).

200 OK

{
  "success": true,
  "message": "Webhook configured successfully",
  "webhook": {
    "label":         "default",
    "enabled":       true,
    "url":           "https://meuapp.com/webhook",
    "authorization": "Bearer secret-key-123",
    "byEvents":      false,
    "events":        ["message.exchange", "call.update"],
    "mediaBase64":   true
  }
}

Path parameters

string

required

Instance name (e.g., $Instance_Name).

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json

Request body

string

default:"default"

Local identifier. Max 50 chars; accepts [a-zA-Z0-9_-]. Empty or omitted becomes "default". Allows multiple webhooks per instance.

boolean

required

Turns the webhook on/off. When false, the url, authorization, byEvents, events and mediaBase64 fields are cleared before saving.

string

Destination URL. Required when enabled=true. Goes through the SSRF guard (see below), blocks localhost, private IPs, link-local, multicast.

string | null

default:"null"

Literal content of the Authorization header sent on each delivery (e.g., Bearer secret-key-123). Encrypted at rest with AES-256-GCM when ENCRYPTION_KEY is configured.

boolean

default:"false"

If true, the URL receives the /<event-name> suffix on each delivery, useful for endpoint-based routing without inspecting the payload (https://app/wh/message.exchange).

string[]

default:"[]"

Filter. Empty array = receive all 6 types. Each entry must be in {message.exchange, message.status, call.update, group.flow, instance.state, label.update}.

boolean

default:"false"

When true, message.exchange events with media include media.base64 (increases payload, may exceed 100KB).

SSRF guard

The url is validated at configuration time and before each delivery. It blocks destinations that point to internal infrastructure:

Range	Example
Loopback	`localhost`, `127.0.0.1`, `::1`
Private IPv4	`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
Link-local IPv4	`169.254.0.0/16`
Link-local IPv6	`fe80::/10`
Multicast / broadcast	`224.0.0.0/4`, `255.255.255.255`

If you need to test against a local server in development, expose it through a public tunnel (ngrok, cloudflared, localhost.run), the SSRF guard is active in every environment.

Notes

Empty authorization vs. null: send null or omit it to skip the header. An empty string "" would result in an empty Authorization: header, which some proxies reject.
enabled=false clears the fields: re-enabling the same label later requires re-sending the url (and any other fields you want to preserve).
There is no DELETE: to “remove” a webhook, POST with {"enabled": false} keeping the label. Operators can inspect/clean the row directly in the database when needed.
Optional encryption: if ENCRYPTION_KEY is not configured, authorization is stored in plain text. In production, always configure the key.
Cache invalidated: the new config becomes visible to the dispatcher immediately (the internal 30s TTL is invalidated on save).

Errors

HTTP	`error.message`
400	`Invalid request body`
400	`URL is required when enabled is true`
400	`URL must not target localhost or private network`
400	`invalid event type: <value>`
400	`label too long (max 50 chars)`
400	`label may only contain letters, digits, underscore or dash`
401	`Invalid token`
404	`Instance not found`
409	`webhook limit reached (max 3 enabled per instance)`
429	`Rate limit exceeded. Try again later.`
500	`Failed to get instance`

Envelope:

{
  "success": false,
  "error": { "message": "URL must not target localhost or private network" }
}

The 3-webhook limit check is only enforced when creating a new row with enabled=true. Editing an existing row (same label) never triggers the limit.

List webhooks

GET /api/events/getWebhook/:instance, all or by ?label=.

Event catalog

What each event carries in data.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Minimum

With label, filter and Authorization

byEvents = true (URL-based routing)

Soft-disable preserving the label

Base64 media (raw backup)

Success response

Path parameters

Headers

Request body

SSRF guard

Notes

Errors

Next

List webhooks

Event catalog

​Description

​Examples

​Minimum

​With label, filter and Authorization

​byEvents = true (URL-based routing)

​Soft-disable preserving the label

​Base64 media (raw backup)

​Success response

​Path parameters

​Headers

​Request body

​SSRF guard

​Notes

​Errors

​Next

List webhooks

Event catalog

Description

Examples

Minimum

With label, filter and Authorization

byEvents = true (URL-based routing)

Soft-disable preserving the label

Base64 media (raw backup)

Success response

Path parameters

Headers

Request body

SSRF guard

Notes

Errors

Next