Custom Webhook Setup Guide

BEFORE YOU START

What you need

• A stable external account identifier
• The ability to send signed HTTPS webhooks
• An optional HTTPS destination if the provider should receive replies

CONNECTION STEPS

Connect Custom Webhook, one click at a time

Complete each small action in order. Do not move to the next step until the expected result matches what you see.

1. 01
   Planning

   Choose the person who controls the other platform

   This person needs access to the provider's webhook or API settings. They may be your developer, vendor, or technical administrator.

   • Write down the name of the external platform.
   • Identify who can add an outbound webhook and HMAC signature there.
   • Ask whether the platform can also receive reply requests at a public HTTPS URL.
   • Keep that person available for the final test.

   Expected resultOne responsible person can configure and test the provider side.

2. 02
   Planning

   Decide the three public identifiers

   These values are labels, not passwords. Keep them stable so future events continue reaching the same SEROS channel.

   • Choose a lowercase Provider key using letters, numbers, underscores, or hyphens, for example shop_chat.
   • Copy the provider's stable account or workspace ID for Provider account ID.
   • Choose a clear SEROS Connection name your team will recognize.

   Expected resultThe connection name, provider key, and provider account ID are ready.

3. 03
   External platform · optional replies

   Collect the outbound destination

   Complete this only if replies sent by agents in SEROS should be delivered back to the external platform.

   • Ask the provider administrator for its public HTTPS reply endpoint.
   • Ask for a dedicated bearer token if the endpoint is protected.
   • Confirm the endpoint does not use localhost, a private network address, or plain http://.

   Expected resultYou have an HTTPS outbound URL and optional bearer token, or you have chosen inbound-only setup.

4. 04
   SEROS

   Create the Custom Webhook connection

   SEROS generates a unique callback URL and signing secret after this form is saved.

   • Open SEROS and select Integrations.
   • Find Custom Webhook and select Connect.
   • Enter the Connection name, lowercase Provider key, and Provider account ID.
   • If replies are needed, paste the HTTPS destination and bearer token, then select Save securely.

   Expected resultFinish setup displays the callback URL and one-time signing secret.

5. 05
   SEROS → external administrator

   Copy and hand off the secret values

   The signing secret is shown only when created or rotated. Transfer it through your company's approved secret-sharing method.

   • Use Copy beside Callback URL and save it in the provider's webhook destination field.
   • Copy the signing secret and place it in the external platform's secret manager.
   • Tell the administrator to sign the exact raw request body with HMAC-SHA256.
   • Tell them to send the signature in the X-Omni-Signature request header.

   Expected resultThe external platform knows where to send events and how SEROS will verify them.

6. 06
   External platform

   Map one real event to the SEROS message contract

   Start with one text-message event before adding files, reactions, or other event types.

   • Map the external user ID to the stable customer identity field.
   • Map the message ID, timestamp, sender direction, text, and provider account ID to the SEROS canonical payload.
   • Send UTF-8 JSON with Content-Type application/json to the callback URL.
   • Keep the original provider message ID stable so retries do not create duplicate messages.

   Expected resultThe external platform can send one correctly signed canonical message event.

7. 07
   SEROS + external platform

   Test inbound and outbound delivery

   Test with controlled data before enabling the webhook for all customers.

   • In SEROS, select Test on the Custom Webhook connection.
   • Send one signed event from the external platform and confirm it creates the expected Unified Inbox conversation.
   • Send a reply from SEROS and confirm it reaches the outbound HTTPS endpoint when configured.
   • Select Activate only after both required directions work.

   Expected resultThe custom channel is Active and handles the controlled test without duplicate messages.

FINAL CHECK

Verify before your team relies on it

• Invalid signatures are rejected
• A valid canonical event creates the expected SEROS conversation
• Provider account identity remains stable across events
• Outbound replies reach the configured HTTPS destination when enabled

IMPORTANT NOTES

Know the provider rules