Opt-in webhooks tell another system, such as your CRM, each time someone opts in to one of your campaigns. mCommons sends a message to a web address you choose, so your system can update the contact right away instead of waiting for a scheduled import.
This article covers setting up and managing webhooks in mCommons. Your developer builds the endpoint that receives them. Send them Receiving Opt-In Webhooks for the technical details.
Note: Mobile Commons turns on opt-in webhooks one account at a time. To turn them on for your account, contact your Customer Success Manager (CSM). After that, users in your account can set up and manage webhooks on the Event Webhooks page. Users with the Campaign Editor role can't see or use this page.
Before you start
Get these from your developer or CRM administrator:
-
The endpoint URL. This is the address mCommons sends opt-ins to. It must start with
https://and be reachable from the public internet. - The opt-ins they want. Decide whether the webhook should cover every opt-in in your account, every opt-in to one campaign, or only opt-ins through one opt-in path.
Also agree on how you'll pass along the signing secret. mCommons shows the secret only once, when you create the webhook. Your developer needs it to confirm that messages come from mCommons.
Creating a webhook
- In the left menu, under Home, select Event Webhooks.
- Select New Webhook.
- Enter a Name. Use something that says what the webhook feeds, such as "Salesforce opt-ins." Each name must be unique in your account.
- Enter the Endpoint URL from your developer.
- For Event type, select Opt In. This is the only event type today.
- Choose which opt-ins the webhook covers:
- Every opt-in in your account: Leave Campaign set to All campaigns.
- Every opt-in to one campaign: Select the campaign, and leave Opt-in path blank.
- Only opt-ins through one opt-in path: Select the campaign, then select the opt-in path.
- Turn on Enabled? if you want the webhook to start sending right away. It's off by default.
- Select CREATE.
- In the Copy the signing secret window, copy the secret and send it to your developer in a secure way, such as a password manager. Don't send it in a regular email or chat.
- Select HIDE KEY FOREVER.
Important: After you close the signing secret window, you can't view the secret again. If it's lost, rotate the secret and share the new one.
Tips:
- The Campaign list shows active campaigns only. The Opt-in path list stays empty until you pick a campaign, then shows that campaign's active opt-in paths.
- If more than one webhook matches an opt-in, each webhook sends its own message.
- A webhook that covers every opt-in sends one message per person when you add a group to a campaign. A large group can send thousands of messages at once. Let your developer know before you do a large bulk add.
What counts as an opt-in
A webhook sends a message when someone:
- Opts in by keyword, QR code, web form or API
- Confirms a double opt-in (after they confirm, not when mCommons first asks them)
- Opts back in after opting out
- Opts in again while already subscribed, for example by texting the keyword a second time
- Joins a campaign through a bulk add, such as adding a group
- Joins through a data sync from your CRM
Numbers on your block list don't trigger a webhook.
Sending a test
Send a test after you create a webhook, before your developer relies on it. A test catches a wrong URL, a firewall block or a signing secret mismatch early.
- On the Event Webhooks page, open the menu on the webhook's row.
- Select Send test.
mCommons sends one sample message right away and shows the result:
- Sent successfully: The endpoint received the test.
- Endpoint rejected the test: The endpoint answered with an error. The message shows the error code.
- Test delivery failed: mCommons couldn't reach the endpoint. The message shows why.
Tests work on webhooks that are turned off too. They show up in the webhook's logs but don't count toward Last Success, Last Failure or Consecutive failures.
Checking on your webhooks
The Event Webhooks list
The Event Webhooks page lists all your webhooks, newest first. Use the search box to find one by name. Each row shows:
- Name and URL
- Event Type: Always Opt In today
- Scope: All opt-ins, or the campaign and opt-in path the webhook covers
- Enabled?: YES or NO
- Last Success: The last time a real opt-in reached the endpoint
- Last Failure: The last time a delivery attempt failed
- Consecutive failures: Failed attempts since the last success
A warning icon appears next to Consecutive failures at 3 or more. That usually means the endpoint is down or rejecting messages. Let your developer know.
When a delivery fails
A delivery fails when the endpoint doesn't answer in time or answers with an error. mCommons tries each opt-in up to 3 times: right away, then 1 minute later, then 5 minutes after that. Each failed attempt adds 1 to Consecutive failures.
After the third failed attempt, mCommons doesn't send that opt-in again. Your developer can use the API to catch up on missed opt-ins.
mCommons never turns off a webhook on its own, no matter how many failures it has.
Viewing the logs
- On the Event Webhooks page, open the menu on the webhook's row.
- Select Logs.
The Logs page lists every delivery attempt and test, newest first:
- Time: When the attempt happened
- Event: The event type
- Status: Success or Failure
- Attempt: Which try this was, out of 3
- HTTP: The response code from the endpoint
- Duration: How long the attempt took
- Error: What went wrong, if it failed
- Payload Sent: The message mCommons sent
- Response: What the endpoint sent back
Hover over a shortened value to see the full text. A new attempt can take a short time to appear in the logs.
The Actions menu on the Logs page has the same options as the row menu.
Managing a webhook
You can't edit a webhook after you create it. To change its name, URL or scope, delete it and create a new one. The new webhook gets a new signing secret and starts with empty logs.
Turning a webhook off and on
- On the Event Webhooks page, open the menu on the webhook's row.
- Select Disable or Enable.
Important: mCommons doesn't save opt-ins that happen while a webhook is off. Turning it back on doesn't send them later. Any retries waiting to go out are also canceled.
Rotating the signing secret
Rotate the secret if it's lost or might have been shared with the wrong person.
- Agree on a time with your developer. The old secret stops working the moment you rotate, so every message fails until the endpoint has the new one.
- On the Event Webhooks page, open the menu on the webhook's row.
- Select Rotate secret and confirm.
- Copy the new secret and send it to your developer in a secure way.
Deleting a webhook
- On the Event Webhooks page, open the menu on the webhook's row.
- Select Delete and confirm.
Deleting a webhook stops it right away, cancels any waiting retries and deletes its logs. You can't undo this. To pause a webhook, turn it off instead.
FAQ
Who can set up opt-in webhooks?
After your CSM turns on opt-in webhooks for your account, any user in your account can set them up, except users with the Campaign Editor role. Webhook settings include the signing secret, so the Campaign Editor role can't see the Event Webhooks page.
Can I choose which profile fields the webhook sends?
No. Each message has a fixed set of details: the phone number, campaign, opt-in path, how the person joined and when they first opted in. See Receiving Opt-In Webhooks for the full list.
Can a webhook send opt-outs or incoming messages?
No. Opt-in webhooks cover opt-ins only. Opt-outs, delivery reports and incoming messages use a separate webhook setup through the Mobile API.
Will I get an alert when a webhook keeps failing?
Not yet. Check Consecutive failures on the Event Webhooks page, or ask your developer to watch for errors on their side.
Why did the same person come through twice?
Someone who opts in again, for example by texting the keyword twice, triggers a new message. A slow response from the endpoint can also lead to a retry. Your developer can handle both. See Receiving Opt-In Webhooks.
Can I get back opt-ins that weren't delivered?
mCommons doesn't resend them. Your developer can use the API to list campaign subscribers for the time that was missed.