Inbound call event processing

Managed integration

POST /api/v1/webhooks/bulkvs/inbound accepts normalized events from an authorized platform/carrier adapter. This is not a public call-creation API for customers. Its payload is Message.com’s adapter contract, not a claim that a carrier emits this exact format natively.

Configure numbers, routing, voicemail and AI through phone settings. Customer webhook subscriptions use the documented product webhook setup instead of this internal endpoint.

Event contract

The required fields are eventId, eventType, from, to and callId. eventType is ringing, answered, ended or voicemail. Optional fields include durationMs, recordingUrl, recordingDurationMs and metadata. The to number identifies an active assigned line.

eventId identifies a delivery for duplicate handling; callId identifies the call. Do not create a new eventId just to retry an unchanged event.

{"eventId": "example-event-1", "eventType": "ended", "from": "+14155550101", "to": "+14155550102", "callId": "example-call-1", "durationMs": 30000}

Authentication

The adapter signs the exact raw request body with the configured workspace relay secret using HMAC-SHA256, sending X-Bulkvs-Signature: sha256=<hex>. The secret stays server-side. Missing secret configuration, an invalid signature or a secret that cannot be decrypted prevents processing.

Interpret acknowledgements

Malformed payloads receive HTTP 200 with ok:false and error:invalid_payload. An unknown destination may be acknowledged with action:dropped_unknown_did. HTTP 200 alone is not proof that a call was routed or answered.

Recording and transcription depend on the call’s configuration and processing state. There is no universal five-second transcript deadline or guaranteed 90-day retention period implied by this endpoint. Check the actual call record and product retention settings.

Verify call behavior

For an end-to-end check, call an assigned number, confirm its greeting and queue, accept it on the intended device, speak in both directions and hang up. Confirm the call ends in the Inbox and any enabled recording/transcript becomes available. A successful webhook request alone cannot validate the audio path.