Switch sectionYour AI and integrations

Event subscriptions: Syncra notifies your service

How to make Syncra send a request to your address when a message arrives, a task is created or a page changes, and how to check the signature.

An event subscription works the other way round from an incoming webhook: you do not write to Syncra, Syncra writes to you. When a chosen event happens, Syncra sends a request describing it to your address. Your service learns that a bot was mentioned, a task was created or a page changed without checking Syncra again and again.

A workspace owner or admin creates a subscription, and it belongs to a bot. Your service needs a public internet address (URL) that accepts POST requests.

How to create a subscription

  1. Open the workspace settings, the Bots tab, and the bot page.
  2. In the Event subscriptions section, enter your address in Request URL.
  3. Tick the Events. They are split into three groups: Chat, Tasks and Wiki.
  4. Press Add subscription.
  5. On the row of the new subscription, press Send test. A message next to the button says the test is queued. The result appears in the Recent deliveries list.

Each subscription has its own signing secret. Your service uses it to check that a request really comes from Syncra, as described below.

Which events exist

  • Bot mentioned, DM received, Message created
  • Task created, Task assigned, Task status changed, Task completed, Task comment added
  • Wiki page created, Wiki page updated

Chat events come only from channels the bot belongs to, and messages written by any bot do not trigger them. Task and page events cover the whole workspace, except changes made by bots. Events about a task or page in a private project go only to the bot that created that project. There are no events for reactions, calls, meetings or CRM deals.

What arrives at your address

A POST request with JSON and three headers: X-Syncra-Event with the event name, X-Syncra-Timestamp with the send time in seconds, and X-Syncra-Signature with the signature. The body describes the event, the workspace, the bot, and the message, task or page.

How to check the signature

The signature looks like v1=<hex>. It is an HMAC SHA-256 of one string made of the timestamp, a dot and the request body, with the subscription secret as the key:

const expected = "v1=" + crypto
  .createHmac("sha256", secret)
  .update(timestamp + "." + rawBody)
  .digest("hex");

Use the request body as received, before parsing the JSON. If the signature matches, the request is from Syncra. Syncra sets no limit on the age of the timestamp, so your service decides how old a request it accepts.

What Syncra does when delivery fails

Any 2xx answer counts as success. If your address answers anything else, does not answer within 5 seconds, or is down, Syncra tries again, up to five attempts in total with growing pauses, starting at one second. After the fifth failure the delivery is marked failed. You cannot resend it by hand. Events can arrive out of order, so your service should rely on the data inside each request, not on the order of arrival.

Updated:

More in “Your AI and integrations”

Back to the category

Didn't find an answer?

Message us on Telegram. A person from the Syncra team replies.

Message us on Telegram