Callback settings
Callbacks let the IM service push changes in the app to your server (event callbacks), and ask your server before users send messages, add friends or join groups (sync callbacks); see the callback overview. This page covers adding callback endpoints in the console, choosing events, turning on sync callbacks, and viewing delivery records and redelivering.
Callbacks are managed in the "Callbacks" tab of app details, which has three sub-tabs:
| Sub-tab | Contents |
|---|---|
| Callback endpoints | Add, edit, verify, test, pause and delete callback endpoints; click an endpoint's name to open its details, with the signing secret, delivery queue, request log and stats, and batch redelivery |
| Sync callbacks | Turn on and configure the four sync callbacks (before sending messages, before sending chat room messages, before adding friends, before joining groups), test them and view stats |
| Event catalog | Every event type, its description and a sample of its data |
Who can do what
Callbacks send user profiles and message content to an address you choose, so adding an endpoint or a subscription opens a channel for data to leave. Changing the config is therefore limited to owner and admin, and actions that change "where data goes and what data goes" also need identity verification:
| Action | owner | admin | developer | Identity verification |
|---|---|---|---|---|
| View callback endpoints, sync callback settings, the event catalog, delivery queue, request log and stats | ✓ | ✓ | ✓ | |
| URL verification, test sends, testing sync callbacks | ✓ | ✓ | ✓ | |
| Pause and resume endpoints, redeliver | ✓ | ✓ | ✓ | |
| Change an endpoint's name, batching, timeout, concurrency and rate; subscribe to fewer events, tighten filters | ✓ | ✓ | ||
| End the old secret's grace period early | ✓ | ✓ | ||
| Create and delete endpoints, change the URL, subscribe to more events, loosen filters | ✓ | ✓ | ✓ | |
| Rotate the signing secret | ✓ | ✓ | ✓ | |
| Turn on, turn off and configure sync callbacks | ✓ | ✓ | ✓ |
developer doesn't see the "New endpoint", "Edit", "Delete" and "Rotate" buttons or the sync callbacks' "Configure" button. All write actions go to the operation log, without signing secrets or event content. While the tenant is suspended or in the closure cooling-off period, the "Callbacks" page is view-only, and verification, tests and redelivery aren't possible either.
Create a callback endpoint
Under "Callback endpoints", click "New endpoint" at the top right (each app can have up to 5 endpoints; the button is disabled at 5) and fill in:
| Field | Description |
|---|---|
| Name | 1 to 64 characters, such as "Business system" or "Message archive" |
| URL | The address that receives callbacks: only https with a public domain, on port 443 or 1024 to 65535; for the rules, see Address requirements |
| Subscribed events | At least one. Grouped by category, where the first item of each group, "category.*", subscribes to all events in the category (including ones added later); see Subscribing to events |
| Don't call back for server-initiated actions | When on, events caused by your server through OpenAPI and by your actions in the console aren't sent, except message recalls; see Filters |
| Don't call back for side effects of deleting users | When on, friendships removed and groups left as a result of deleting a user aren't sent one by one |
| Message conversation types | Whether message events cover one-to-one, group, or both |
| Receive group notice messages | Whether message copies include group notices; not by default |
| Events per batch | 1 to 100, default 1. Above 1, one request carries several events, which suits high-volume events such as message copies |
| Timeout (milliseconds) | 1000 to 10000, default 5000 |
| Max concurrency | 1 to 50, default 10 |
| Requests per second | 1 to 1000, default 100, not above the app's limit (shown under the field, 500 by default, across all endpoints) |
Click "Save" and verify your identity as prompted. After saving:
- A dialog shows the endpoint's signing secret (starting with
cbs_), only this once; copy it into the receiver's config, then click "I've saved the secret". If you forget, rotate the secret. - The system immediately sends the URL a URL verification request and shows the result in the dialog. Once it passes, the endpoint is "Active" and starts delivering events; if not, it's "Pending verification" and doesn't deliver.
URL verification and test sends are limited to 20 per minute per app combined. When that's used up, the endpoint is still saved as "Pending verification", and the dialog says to click "Verify" in the list later.
Get signatures working before verifying
You can save the endpoint before the receiver is ready: use "Test" to send an event, get signature verification working against the request body in the result, then click "Verify". For how to verify signatures and sample code, see Verifying callback requests.
Callback endpoint list
| Column | Description |
|---|---|
| Name | Click to open the endpoint details |
| URL | Query parameter values show as ***; see below |
| Subscriptions | The number of events subscribed; hover to see them all |
| Status | Pending verification, active, paused, auto-disabled or disabled by platform; for what they mean, see Endpoint status; hover for the reason it was disabled. A "Sync callback" tag shows when a sync callback is bound to the endpoint |
| Health | "Healthy", or "Failing since …" (hover for the last error and failure time); circuit breaking and backlog counts |
| Actions | Edit, verify, test, pause or resume, delete |
Above the list are the per-second request limit for all the app's endpoints combined, and the egress IPs of callback requests (when the platform configured them), which you can add to the receiver's firewall allowlist.
Verify
Click "Verify" to send the endpoint a URL verification request and see the result: success or failure, the reason for failure (such as "Connection failed", "Non-2xx status" or "Wrong challenge"), the HTTP status, time taken, the peer IP and the start of the response. An endpoint "Pending verification" becomes "Active" once it passes; for other statuses, verifying doesn't change the status and only checks that the receiver works.
Test send
Click "Test" and choose an event type (it needn't be subscribed); the system builds an event from the event catalog's sample data (with test true) and sends it immediately, without putting it in the delivery queue. Besides everything in a verification result, the result includes the full request body sent, to help debug signatures. Testing doesn't require the endpoint to be verified, except for endpoints disabled by the platform.
Edit an endpoint
Click "Edit", change the settings and save. Leaving the URL empty means unchanged: the URL in the list has query parameter values replaced with ***, so to change the URL, enter the full new URL (it can't be saved with a query value of ***).
- Identity verification is needed when changing the URL, subscribing to more events (replacing
group.*withgroup.createdisn't more, the reverse is), or loosening filters (turning off "Don't call back for server-initiated actions" or "Don't call back for side effects of deleting users", turning on "Receive group notice messages", or adding message conversation types). Other changes don't need it. - After changing the URL, the endpoint goes back to "Pending verification" and the system immediately sends the new URL a verification and shows the result. Until it passes, no events are delivered, and sync callbacks bound to the endpoint are treated as failed too (those with the failure policy "Reject" reject the matching actions). Rebind sync callbacks to another endpoint first, or switch them to "Allow" for now.
- Changing subscriptions and filters only affects later events; events already queued are sent as usual.
- When two people edit the same endpoint at once, the later save says the data was changed; refresh and edit again.
Pause and resume
When the receiver is down for maintenance, click "Pause": events still queue but aren't sent, and sending continues after resuming. Each event not sent within 24 hours of queuing becomes a failed delivery (counted from when it queued, not from the pause), and can be redelivered within 7 days. Pausing doesn't affect sync callbacks.
Click "Resume":
- A "Paused" endpoint goes straight back to "Active".
- An "Auto-disabled" endpoint (disabled by the system after failing for 24 hours; see Persistent failures and auto-disable) first gets a URL verification; if it passes it becomes "Active", otherwise it stays disabled and shows the result. After resuming, batch redeliver the events that failed before it was disabled; events from while it was disabled weren't queued and won't be sent.
Endpoints "Pending verification" can't be resumed; click "Verify" instead.
Delete an endpoint
owner and admin click "Delete" and confirm (with identity verification). Delivery stops immediately, sync callbacks bound to the endpoint are turned off, and queued events and request logs are deleted afterward and can't be recovered.
Endpoints disabled by the platform
When the platform disables an endpoint (usually because it points to a third party that isn't yours), its status is "Disabled by platform", and the top of its details shows the reason. While disabled, no events are delivered and sync callbacks bound to it are treated as failed; you can't change its URL, delete, verify, test or redeliver, and it still counts toward the limit of 5 endpoints. If you disagree, contact us and the platform can restore it.
Endpoint details
Click an endpoint's name to open its details; the top shows its settings and health:
| Item | Description |
|---|---|
| Status, endpoint ID | The endpoint ID is the X-IM-Endpoint-Id request header |
| Batch / timeout, concurrency / per second | The current settings; when the platform lowered the app's limit, the actual requests per second may be lower, marked "Limited by app limit" |
| Last success, last failure | When an event callback last succeeded and failed, and why it failed |
| Failing since | When failures began after the last success; after 1 hour owner and admin are notified, and after 24 hours it's auto-disabled |
| Backlog | The number of events waiting for delivery and the limit (500,000 by default), plus when the oldest one queued, refreshed about every 30 seconds |
| Circuit breaker | Normal, open or probing; see Retries |
| Verified | When it last passed URL verification |
| Signing secret | The current secret's version and first 8 characters; see below |
Below are four tabs: delivery queue, request log, stats, and batch redelivery.
Signing secret
Details only show the secret's first 8 characters (such as cbs_Le8E…) to recognize it; the full secret is only shown once, when creating the endpoint and when rotating.
- Rotate:
ownerandadminclick "Rotate", enter the old secret's grace period (1 to 168 hours, 24 by default), confirm and verify their identity, and the dialog shows the new secret (only this once). The new secret takes effect immediately; during the grace period each request carries signatures from both, so the receiver passes with either, and details show "Old secret … has a grace period until …". You can't rotate again before the grace period ends. - End the grace period early: once every receiver has the new secret, click "End grace period early", after which only the new secret signs and receivers still using the old one fail verification. No identity verification needed.
For replacing the secret without downtime, see Rotating secrets. Secrets don't expire on their own.
Delivery queue
See the endpoint's deliveries by status:
| Status | Contents |
|---|---|
| Pending | Events queued or waiting to retry, ordered by next send time |
| Failed (shown by default) | Events not delivered within 24 hours, kept for 7 days and redeliverable |
| Delivered | Successfully delivered events, kept for 1 hour |
Filter by event type, or enter an event ID (such as events[].id from your receiver's logs) under "Look up by event ID" to find that event's delivery to this endpoint. The list shows the event type, event ID, status, send count, last error and status code, next send or completion time, and queuing time.
- Details: the event's time, send count, ID of the last request, and the event's
data. Message events (message copies, message edits, chat room message copies) don't showbodyandext; content isn't kept after successful delivery. - Redeliver: click "Redeliver" on a failed event to put it back in pending, with the send count reset and the 24-hour limit restarted. The endpoint must be "Active" or "Paused" (paused ones queue it and send after resuming).
Request log
Every request sent to the endpoint, kept for 7 days, filterable by result (success, failure) and type (event, sync callback, URL verification, test):
| Column | Description |
|---|---|
| Time, type | Redelivery requests also get a "Redelivery" tag |
| Name | The event type or sync callback type; batched sends note the number of events |
| Attempt | Which send of the event this was |
| Result | Success (sync callbacks also show the result, such as allow, reject, modify or fallback_allow), or the reason for failure |
| HTTP, time, peer IP | The status the receiver returned, how long the request took, and the IP actually connected to |
Expand a row to see the request ID (the X-IM-Request-Id header), the event IDs it included, the error description, the start of the receiver's response and the request body size. The request log doesn't keep event content. URL verifications, tests, redeliveries and failed requests are almost all recorded, while successful requests are sampled; full counts are in the stats.
Reasons for failure:
| Reason | Description |
|---|---|
| DNS resolution failed | The URL's domain couldn't be resolved |
| Resolved to a non-public address, or refused by the egress proxy | The IP to connect to isn't public, so it was refused before connecting |
| Connection failed | Connection refused, unreachable or timed out |
| TLS handshake failed | The certificate is invalid, expired or doesn't match the domain |
| Timeout | The response wasn't read completely within the timeout |
| Non-2xx status | The receiver returned 4xx, 5xx or similar; the status is in parentheses |
| Redirect returned (not followed) | The receiver returned 3xx |
| Response too large | A sync callback or URL verification response exceeded the limit |
| Invalid response | A sync callback returned 2xx but the body doesn't meet the requirements; see Sync callback responses |
| Wrong challenge | The URL verification response doesn't have the right challenge |
Stats
Stats for the last 24 hours or 7 days, kept for 90 days:
- By event type: each event type's queued, delivered, failed, dropped (the backlog hit its limit, or presence and chat room events were dropped because a buffer was full) and skipped (no delivery was created because the endpoint wasn't active or paused, or the app was unavailable) counts.
- By hour: requests, failures, timeouts, skips while the circuit breaker was open, average and maximum time taken, events delivered, and the average and maximum delay from an event happening to its successful delivery.
Batch redelivery
Once the receiver is fixed, redeliver in bulk by failure time: choose the failure time range (at most 7 days apart), optionally just a few event types, and click "Redeliver". Up to 10,000 events are handled each time; when it says "More remain", submit again. The endpoint must be "Active" or "Paused"; resume "Auto-disabled" endpoints first.
Sync callbacks
"Sync callbacks" lists the four sync callbacks; see Sync callbacks:
| Column | Description |
|---|---|
| Sync callback | Before sending messages (message.before_send), before sending chat room messages (chatroom.before_send), before adding friends (friend.before_add), before joining groups (group.before_join) |
| Status | On or off. When on but the bound endpoint is "Pending verification" or "Disabled by platform", "Endpoint unavailable" also shows: no requests are sent, the failure policy applies, and with "Reject" every matching action is rejected |
| Bound endpoint | The callback endpoint called |
| Wait | How long to wait for a response |
| On failure | Allow or reject |
| Actions | Configure, test, stats |
Configure a sync callback
owner and admin click "Configure", and saving needs identity verification:
| Field | Description |
|---|---|
| On | Turns this sync callback on or off. Other settings are kept when off |
| Endpoint to call | Required when on. Endpoints "Pending verification" or "Disabled by platform" can't be chosen |
| Wait time (milliseconds) | 100 to 3000, default 1000. The actual wait doesn't exceed the time the action has left: all pre-send checks for a message share 3 seconds in total, and chat room messages 500 milliseconds |
| On timeout, error or invalid response | Allow (default) or reject; see Handling failures |
| Conditions | Differ by type: before sending messages, the sending entry, conversation type, message type, whether to include online-only messages and whether to include edits; before sending chat room messages, the sending entry, message type and priority; before adding friends, the stage (sending a request, accepting a request); before joining groups, how they join and the group type. Actions not matching the conditions are allowed directly. See Sync callbacks |
Changes usually take effect within 1 second. Before turning on "Reject on failure", make sure the receiver is stable: if it fails, the matching action fails for the whole app.
Test and stats
- Test: sends one sync callback request with sample data to the bound endpoint (which needn't be verified) and shows whether it succeeded, your server's decision (such as
allow), or why the response was invalid. It can't test without a bound endpoint. - Stats: per hour for the last 24 hours: calls; allow, reject, modify and failure counts; requests not sent because of timeouts, insufficient time, the circuit breaker or an unavailable endpoint; allows and rejects by policy after failures; and the average time taken.
Event catalog
"Event catalog" lists every event type you can subscribe to, its category and description, filterable by category; expand a row to see a sample of its data, which is what test sends use. For each event's fields, see Event callbacks.
Subscribing to standalone channel events
Channel events are in the audio/video category, with types starting with rtc_channel.; for the full list, see Channel events. Choose rtc_channel.* to subscribe to all 9 channel events; the call events' rtc.* doesn't include them. Internal notifications of config changes aren't sent to you as callbacks. Subscribing to more still needs identity verification under this page's rules, and the receiver must handle duplicate and out-of-order events.