Skip to main content
POST
Use this reference to inspect the webhook payloads that YCloud sends to your application. Select a named example in the request builder to view its fields. The reference uses https://example.com as a reserved placeholder. For your own tests, replace it with your application’s webhook URL in the generated request. Your application hosts this endpoint; YCloud does not host /webhooks/ycloud.
Sending a sample payload tests your receiver. It does not trigger a webhook delivery from YCloud. The example YCloud-Signature is a sample value; it is not a valid signature for an edited payload or your endpoint’s secret.
Validate the YCloud-Signature header before processing an event. See Configure webhooks for setup and delivery guidance.

​
Receiver response

Return any 2xx status after you have authenticated and durably accepted the event. Process slow work asynchronously so YCloud does not retry a delivery that your application already received.

Configure webhooks

Create an endpoint, validate signatures, and handle retries.

Browse annotated examples

Understand event triggers and scenario-specific handling.

Headers

​
YCloud-Signature
string
Example:

"t=1654084800,s=8eb70f2acb056c2119acbee8fdd98a889021d9c268bc9ad248a4182c40e31119"

Body

application/json

Represents a webhook event payload. Every event contains certain common properties: id, type, apiVersion, createTime. Each event may also contain some properties unique to the event. For example, sms is returned when type is sms.message.updated.

​
type
enum<string>
required

Type of event.

Available options:
whatsapp.echo_message.created,
whatsapp.echo_message.updated
​
whatsappMessage
object
required

Included when type is whatsapp.message.updated, whatsapp.smb.message.created, or when type is whatsapp.smb.history for an outbound history message. Also included for whatsapp.echo_message.created and whatsapp.echo_message.updated, where the Agent echo subset applies. It is omitted for a metadata-only history chunk.

​
id
string
required

Unique ID for the event.

Required string length: 6 - 128
​
apiVersion
string
required

The API version used to render this event.

Example:

"v2"

​
createTime
string<date-time>
required

The time at which this event was created, formatted in RFC 3339. e.g., 2022-06-01T12:00:00.000Z.

Example:

"2022-06-01T12:00:00.000Z"

​
phase
integer<int32>

Included when type is whatsapp.smb.history and the event was generated from a Meta history chunk. Identifies the chunk's synchronization phase.

Example:

1

​
progress
integer<int32>

Included when type is whatsapp.smb.history and the event was generated from a Meta history chunk. Reports the chunk's synchronization progress.

Example:

73

​
contactAttributesChanged
object

Included when type is contact.attributes_changed.

​
contactCreated
object

Included when type is contact.created.

​
contactDeleted
object

Included when type is contact.deleted.

​
contactNote
object

Included when type is contact.note.created, contact.note.updated, or contact.note.deleted.

​
contactUnsubscribeCreated
object

Included when type is contact.unsubscribe.created.

​
contactUnsubscribeDeleted
object

Included when type is contact.unsubscribe.deleted.

​
emailDelivery
object

Included when type is email.delivery.updated.

​
sms
object

Included when type is sms.message.updated.

​
smsInbound
object

Included when type is sms.inbound.received.

​
voice
object

Included when type is voice.message.updated.

​
whatsappBusinessAccount
object

Included when type is whatsapp.business_account.deleted, whatsapp.business_account.reviewed, or whatsapp.business_account.updated.

​
whatsappInboundMessage
object

Included when type is whatsapp.inbound_message.received, or when type is whatsapp.smb.history for an inbound history message. It is omitted for a metadata-only history chunk.

​
whatsappMetaBusinessAgent
object

Included for whatsapp.meta_business_agent.handover.updated. Currently limited to Public REST API Agents.

​
whatsappGroup
object

Included when type is whatsapp.group.lifecycle_update, whatsapp.group.participants_update, whatsapp.group.settings_update, whatsapp.group.status_update, or when type is whatsapp.message.updated for group message status updates.

​
whatsappPhoneNumber
object

Included when type is whatsapp.phone_number.deleted, whatsapp.phone_number.name_updated, whatsapp.phone_number.quality_updated, or whatsapp.phone_number.business_username_updated.

​
whatsappPayment
object

Included when type is whatsapp.payment.updated.

​
whatsappTemplate
object

Included when type is whatsapp.template.reviewed, whatsapp.template.quality_updated, whatsapp.template.category_updated, or whatsapp.template.correct_category_detection.

​
callingConnect
object

Included when type is whatsapp.call.connect.

​
callingTerminate
object

Included when type is whatsapp.call.terminate.

​
callingStatusUpdated
object

Included when type is whatsapp.call.status.updated.

​
callingRecording
object

Included when type is whatsapp.call.recording.updated.

​
callingTranscription
object

Included when type is whatsapp.call.transcription.updated.

​
flowChanges
object

Included when type is whatsapp.flow.status_change.

​
whatsappUserPreference
object

Included when type is whatsapp.user.preferences.

Response

200

The request is successfully accepted.