POST /api/webhooks/ingest?type=<event_type>Sends one WhatsApp notification to one recipient using an approved UTILITY template.
Headers
| Header | Required | Value |
|---|---|---|
x-api-key | Yes | Your workspace key |
Content-Type | Yes | application/json |
Query parameters
| Parameter | Required | Description |
|---|---|---|
type | Yes | appointment, delivery or status-update. status_update is also accepted |
business | No | A group id, when one workspace runs several businesses. Omit for the workspace default |
dry_run | No | 1 to validate only. Nothing is queued or sent |
test_send | No | 1 to queue the composed text as a free-form message without a template |
Body fields
The body is JSON. It must provide `recipient_phone` plus one value for each blank in the template chosen for this event on its Notification page. Any approved UTILITY template works with any event type.
If you saved a field mapping, MsgOrb reads each value from the path you gave it. A value the mapping leaves empty is taken from a top-level field with the same name as the blank, and then from the backup value set on the Notification page, if any (never for recipient_phone). So a body that already uses the template's names works as sent. Line breaks and tabs inside values are turned into spaces, because Meta rejects them.
The starter templates each page can create use the names below, so with a starter template these are the fields to send.
type=appointment
| Field | Required |
|---|---|
recipient_phone | Yes |
client_name | Yes |
appointment_time | Yes |
service_type | Yes |
type=delivery
| Field | Required |
|---|---|
recipient_phone | Yes |
customer_name | Yes |
order_id | Yes |
delivery_status | Yes |
tracking_url | Yes |
type=status-update
| Field | Required |
|---|---|
recipient_phone | Yes |
subject_name | Yes |
current_status | Yes |
recipient_phone must be full international format with the country code. MsgOrb rejects anything it cannot resolve unambiguously rather than guessing a country.
Request example
curl -X POST \
"https://www.msgorb.com/api/webhooks/ingest?type=delivery" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipient_phone": "+12145550123",
"customer_name": "Jane Doe",
"order_id": "A-10423",
"delivery_status": "Out for delivery",
"tracking_url": "https://track.example.com/A-10423"
}'Success response
{
"success": true,
"message": "Notification received and queued successfully",
"event_type": "delivery"
}Status 202. The message is queued; the dispatcher sends it within moments and the outcome appears on Delivery and Queue Health.
Error response
{
"success": false,
"error": "No template configured for 'delivery'. Open Notifications, and choose an approved UTILITY template to send."
}Every status code is listed in Notification errors.
Behaviour worth knowing
- MsgOrb stores the most recent payload it receives per event type and uses it to suggest mappings in the field mapper. Send one real event early, even if it is rejected.
- Recipients who replied STOP are refused with 403. This is enforced, not advisory.
- Every call is written to the Connection Logs on the matching Notification page with its real status.