CRM webhook delivery health

Understand delivery commands, activity notifications, retries, and the checks needed before launch.

Delivery commands and notifications are different

The endpoint POST /webhooks/crm/inbox distinguishes a request to send a message from a notification about a message already recorded in the CRM.

• Provider commands: SMS or Email. These ask Beam to send through the configured workspace provider. They must pass signature, workspace, contact, and channel checks. Email additionally requires the separate email provider configuration.
• Marketplace notification: OutboundMessage. This describes existing CRM activity. Beam records a small, deduplicated receipt and acknowledges it. It does not send the message again, copy the activity into another conversation, or change delivery status. The notification itself is not proof that a recipient received a message.
• Contact notification: ContactUpdate. For an active connected workspace, Beam can fill blank names and CRM links on an existing phone contact. The phone and existing CRM link must match. It does not create contacts, change phone numbers, overwrite existing names, or turn off an existing opt-out. Affirmative CRM SMS opt-outs are respected. If the phone is missing or invalid, Beam records the notification without changing a contact. Email-only contacts and a full contact-directory import are outside this handler.

Do not change an OutboundMessage notification into an SMS command to make an error disappear. That can send an existing message a second time. Other event families are not automatically accepted by this endpoint.

If HighLevel reports a low success rate

1. Open the BEAM app in the HighLevel Marketplace dashboard and inspect a failed delivery. Record its event type, time, response code, and request identifier. Do not share its message body, credentials, or contact details.
2. Compare the response with the Beam server log. A 400 means the payload was rejected; a 401 means its signature was not accepted. A timeout or connection error needs a separate network check.
3. Check whether the app is sending activity notifications to the provider delivery URL. The two payload types have different purposes and fields.
4. After a repair, observe naturally arriving events. Notifications should receive a successful response only after their receipt is stored. A storage outage returns 503 so the sender can retry.
5. Verify one approved test message separately from notification health: one send, one recipient delivery, and the expected CRM timeline entry. A successful webhook response alone does not prove delivery.

Workspace and privacy boundaries

Notification receipts are associated only with an active installation matching the signed location. If no active installation exists, Beam records an ignored receipt without assigning it to a workspace. Receipts store a digest and disposition, not message text, addresses, attachments, or raw payloads. A contact receipt and its permitted contact update commit together; failed storage is retried. Notification handling never sends messages or changes billing or voice routing.

What to expect after a repair

The alert covers a rolling monitoring window, so its percentage may remain low while old failures age out. Use recent successful deliveries as immediate evidence. If delivery has been disabled in the Marketplace dashboard, an authorized app administrator must check its status before declaring recovery.

References: provider delivery commands, outbound activity notifications, and signature and retry rules.