Check Webhooks

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

Description

Read endpoint. Without query, returns all webhooks (enabled and disabled) on the instance. With ?label=<name>, returns the single webhook with that label (or 404).

Examples

List all

Without a query string, returns the webhooks[] array with all webhooks on the instance (enabled and disabled), sorted alphabetically by label.

curl -X GET "https://ryzeapi.cloud/api/events/getWebhook/$Instance_Name" \
  -H "token: $Token_Instance"

await fetch(`https://ryzeapi.cloud/api/events/getWebhook/${process.env.Instance_Name}`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/events/getWebhook/{os.environ['Instance_Name']}",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/events/getWebhook/"+os.Getenv("Instance_Name"), nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

A specific one

Passing ?label=analytics-pipeline, returns just the webhook with that label in the envelope’s webhook field (or 404 if it doesn’t exist).

curl -X GET "https://ryzeapi.cloud/api/events/getWebhook/$Instance_Name?label=analytics-pipeline" \
  -H "token: $Token_Instance"

await fetch(`https://ryzeapi.cloud/api/events/getWebhook/${process.env.Instance_Name}?label=analytics-pipeline`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/events/getWebhook/{os.environ['Instance_Name']}?label=analytics-pipeline",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/events/getWebhook/"+os.Getenv("Instance_Name")+"?label=analytics-pipeline", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Explicit default

Fetches the default webhook by passing ?label=default. Useful when you created the webhook without specifying a label and want to read just that entry instead of the full list.

curl -X GET "https://ryzeapi.cloud/api/events/getWebhook/$Instance_Name?label=default" \
  -H "token: $Token_Instance"

await fetch(`https://ryzeapi.cloud/api/events/getWebhook/${process.env.Instance_Name}?label=default`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/events/getWebhook/{os.environ['Instance_Name']}?label=default",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/events/getWebhook/"+os.Getenv("Instance_Name")+"?label=default", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Success response

Without ?label=, returns webhooks[] (sorted alphabetically by label, always present, comes back as [] if no webhook exists, and also includes the ones with enabled=false for operational inspection). With ?label=<name>, returns the single object in webhook (same shape as POST). The authorization is decrypted when ENCRYPTION_KEY is configured; if the key was rotated and some value cannot be decrypted, the field is returned encrypted instead of failing the request.

200 OK (list, no ?label=)

{
  "success": true,
  "message": "Webhook configurations retrieved",
  "webhooks": [
    {
      "label":         "analytics-pipeline",
      "enabled":       true,
      "url":           "https://analytics.meuapp.com/events",
      "authorization": "Bearer svc-token-xyz",
      "byEvents":      false,
      "events":        ["message.exchange", "message.status"],
      "mediaBase64":   false
    },
    {
      "label":       "default",
      "enabled":     true,
      "url":         "https://meuapp.com/webhook",
      "byEvents":    false,
      "events":      [],
      "mediaBase64": false
    },
    {
      "label":       "legacy",
      "enabled":     false,
      "url":         "",
      "byEvents":    false,
      "events":      [],
      "mediaBase64": false
    }
  ]
}

200 OK (?label=analytics-pipeline)

{
  "success": true,
  "message": "Webhook configuration retrieved",
  "webhook": {
    "label":         "analytics-pipeline",
    "enabled":       true,
    "url":           "https://analytics.meuapp.com/events",
    "authorization": "Bearer svc-token-xyz",
    "byEvents":      false,
    "events":        ["message.exchange", "message.status"],
    "mediaBase64":   false
  }
}

array

Present only when there is no ?label=. Sorted alphabetically by label. Always returned even when no webhook exists (webhooks: []).

object

Present only when ?label=<name> is used. Same shape as POST.

Path parameters

string

required

Instance name.

Headers

string

required

TokenAccount or TokenInstance.

Query parameters

string

When present, returns a single webhook (webhook in the envelope). When absent, returns the list (webhooks[]).Passing ?label= (empty) is still considered “present” → it becomes "default" and looks up the row with that label.

Listing includes enabled=false, operators see the full history. To list only active ones, filter on the client by w.enabled === true.
authorization decrypted: if ENCRYPTION_KEY is configured and the value is encrypted at rest, the repository decrypts it before returning. If the key was rotated and a value cannot be decrypted, the field is returned encrypted (with a warning in the log) instead of failing the request.

Delivery: queue, retry, DLQ

Webhook delivery is async and persisted. Every event that matches a webhook is enqueued in webhook_queue and processed by parallel workers.

Flow

EventsService.sendWebhook()
   └─► webhook_queue.Enqueue()        [INSERT row, status=pending]
                                          │
WebhookDispatcher (4 workers + janitor) ──┘
   ├─► ClaimNext()  (FOR UPDATE SKIP LOCKED)
   ├─► HTTP POST + SSRF re-check
   ├─► MarkDelivered (2xx)
   ├─► MarkRetry (4xx except 408/429, redeliver; 408/429/5xx, retry)
   └─► MarkFailed (attempts > max_attempts → DLQ)

Janitor: every 15min, DELETE rows delivered > 24h ago.

Exponential backoff

Attempt	Next retry
1 (fail)	+1s
2 (fail)	+5s
3 (fail)	+30s
4 (fail)	+5min
5 (fail)	+30min
6+	+1h (cap)

After max_attempts (default 5), status becomes failed (DLQ). The row is not deleted automatically, operators can inspect last_error and re-enqueue manually (UPDATE webhook_queue SET status='pending', next_retry_at=now()).

`webhook_queue` table (ops summary)

Column	Description
`id`	`BIGSERIAL` PK
`instance_name`	Instance name
`url`	Final destination (already with `/event-name` suffix if `byEvents`)
`payload`	`BYTEA`, JSON body of the event
`auth_header`	Configured `Authorization` (encrypted at rest)
`event_type`	Event name (`message.exchange` etc.)
`status`	`pending` \| `delivered` \| `failed`
`attempts`	Attempt counter
`max_attempts`	Default 5
`next_retry_at`	Next attempt window
`last_error`	Last error message from the consumer
`created_at` / `updated_at`	Timestamps

Delivered headers

Each POST to your webhook arrives with:

POST <url> HTTP/1.1
Host: <your-host>
Content-Type: application/json
Authorization: <config.authorization>      # if configured
User-Agent: RyzeAPI/<version>

{ "event": "...", "data": { ... }, "instanceData": { ... } }

There is no automatic HMAC. Origin validation is the consumer’s responsibility, configure an authorization (Bearer token, API key) and validate it on your endpoint.

Errors

HTTP	`error.message`	Applies to
400	`label too long (max 50 chars)`	`?label=`
400	`label may only contain letters, digits, underscore or dash`	`?label=`
401	`Invalid token`	both
404	`Instance not found`	both
404	`Webhook not configured for this label`	`?label=`
429	`Rate limit exceeded. Try again later.`	both
500	`Failed to get instance`	both
500	`Failed to list webhook configurations`	no query

Envelope:

{
  "success": false,
  "error": { "message": "Webhook not configured for this label" }
}

Configure webhook

POST /api/events/webhook/:instance

Event catalog

Schemas of the 6 event types.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

List all

A specific one

Explicit default

Success response

Path parameters

Headers

Query parameters

Delivery: queue, retry, DLQ

Flow

Exponential backoff

`webhook_queue` table (ops summary)

Delivered headers

Errors

Next

Configure webhook

Event catalog

​Description

​Examples

​List all

​A specific one

​Explicit default

​Success response

​Path parameters

​Headers

​Query parameters

​Delivery: queue, retry, DLQ

​Flow

​Exponential backoff

​webhook_queue table (ops summary)

​Delivered headers

​Errors

​Next

Configure webhook

Event catalog

Description

Examples

List all

A specific one

Explicit default

Success response

Path parameters

Headers

Query parameters

Delivery: queue, retry, DLQ

Flow

Exponential backoff

`webhook_queue` table (ops summary)

Delivered headers

Errors

Next