Skip to main content

Event Lifecycle

This page explains how to interpret Red Cloud lifecycle events after a send request is accepted.

The send response gives you acceptance into Red Cloud. Webhooks give you later state transitions.

The two layers of state​

Your integration should treat outbound messaging as two separate layers:

  1. request acceptance
  2. later delivery lifecycle

Example:

  • POST /api/core/messages/send returns 202
  • result status returns QUEUED
  • later webhook events describe what happened next

Those are not duplicates. They represent different points in the lifecycle.

Standard outbound progression​

Typical successful progression:

  1. message.queued
  2. message.sent
  3. message.delivery

Typical failed progression:

  1. message.queued
  2. message.failed

Some messages may produce additional operational complexity in the future, but your integration should already be able to handle:

  • success progression
  • failure progression
  • retries of the same webhook event
  • out-of-order processing risk inside your own systems

What each event means​

message.queued​

Meaning:

  • Red Cloud accepted the outbound request into its queueing path

What you should do:

  • persist messageId
  • persist externalReference
  • record that Red Cloud accepted the request

What you should not do:

  • do not treat this as carrier delivery

message.sent​

Meaning:

  • Red Cloud successfully advanced the message into the provider send path

What you should do:

  • update internal status to reflect that the send advanced beyond queue acceptance

What you should not do:

  • do not treat this as final handset delivery

message.delivery​

Meaning:

  • delivery confirmation was received and surfaced through the Red Cloud public webhook contract

What you should do:

  • mark the message as delivered in your own system if that is your final success state
  • persist providerMessageRef if present and useful for support

message.failed​

Meaning:

  • the outbound send reached a terminal failure outcome under the public lifecycle contract

What you should do:

  • persist the failure details
  • decide whether your business workflow needs retry, alternate contact logic, or manual intervention

Ordering and sequence​

For outbound events, use sequence as the ordering field.

That means:

  • persist the highest processed sequence per messageId
  • make event handling idempotent
  • avoid applying older lifecycle updates after newer ones were already accepted

Recommended rule:

Only apply an outbound event if its sequence is greater than the highest already-processed sequence for that message.

Correlation model​

The most useful fields for correlation are:

  • messageId
  • externalReference
  • sequence
  • eventType

Recommended operational pattern:

  • use externalReference to map back to your business object
  • use messageId as the Red Cloud tracking key
  • use sequence to maintain lifecycle ordering

Inbound event handling​

message.inbound is different from outbound lifecycle events.

It represents a new inbound customer message and should be handled as message creation, not as an update to a prior outbound lifecycle.

Persist and use:

  • messageId
  • conversationId
  • numberId
  • from
  • to
  • body
  • media

Common lifecycle mistakes​

  • treating QUEUED as final delivery
  • ignoring sequence
  • failing to deduplicate retried webhook deliveries
  • using only phone number values and not persisting messageId
  • mixing inbound event logic with outbound lifecycle logic

Your internal model does not need to copy every Red Cloud field exactly, but it should at minimum distinguish:

  • accepted
  • sent
  • delivered
  • failed

If your system collapses all outbound states into one generic status too early, support teams lose visibility and debugging becomes harder.