API reference

Event feed

Read the events webhooks deliver, for polling and for catching up after an outage.

List events#

GET/v1/eventsScopewebhooks:read

Returns the events of the key mode, newest first: the same objects webhooks deliver, whether or not an endpoint was subscribed. Use it as a polling fallback and to catch up after your endpoint was down. Events are kept for 30 days.

Query parameters

typestringOptional
Only events of this type.
created_aftertimestampOptional
Only events created after this ISO-8601 timestamp.
limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of events.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/events

curl "https://api.omnimessage.co/v1/events?type=message.delivered&created_after=2026-10-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "evt_6hJ9kL2zX5cV8bN1mQ4w",
      "object": "event",
      "type": "message.delivered",
      "mode": "live",
      "created_at": "2026-10-05T09:30:02.900Z",
      "data": {
        "object": {
          "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
          "object": "message",
          "mode": "live",
          "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
          "channel_type": "whatsapp",
          "direction": "outbound",
          "to": "+971501234567",
          "from": "+971800123456",
          "type": "text",
          "content": {
            "text": {
              "body": "Your code is 482910"
            }
          },
          "status": "delivered",
          "error": null,
          "reference": "order-1042",
          "metadata": {
            "user_id": "u_17"
          },
          "billing": {
            "source": "package",
            "amount_micros": 0,
            "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD",
            "refunded": false
          },
          "sender": null,
          "contact_id": null,
          "created_at": "2026-10-05T09:30:00.000Z",
          "updated_at": "2026-10-05T09:30:02.871Z",
          "sent_at": "2026-10-05T09:30:01.210Z",
          "delivered_at": "2026-10-05T09:30:02.871Z",
          "read_at": null,
          "failed_at": null
        }
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve an event#

GET/v1/events/{id}Scopewebhooks:read

Returns one event by the ID webhooks carry in OmniMessage-Event-Id.

Path parameters

idstringRequired
Event ID.

Responses

200
The event. Event object.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/events/{id}

curl https://api.omnimessage.co/v1/events/evt_6hJ9kL2zX5cV8bN1mQ4w \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "evt_6hJ9kL2zX5cV8bN1mQ4w",
  "object": "event",
  "type": "message.delivered",
  "mode": "live",
  "created_at": "2026-10-05T09:30:02.900Z",
  "data": {
    "object": {
      "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
      "object": "message",
      "mode": "live",
      "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
      "channel_type": "whatsapp",
      "direction": "outbound",
      "to": "+971501234567",
      "from": "+971800123456",
      "type": "text",
      "content": {
        "text": {
          "body": "Your code is 482910"
        }
      },
      "status": "delivered",
      "error": null,
      "reference": "order-1042",
      "metadata": {
        "user_id": "u_17"
      },
      "billing": {
        "source": "package",
        "amount_micros": 0,
        "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD",
        "refunded": false
      },
      "sender": null,
      "contact_id": null,
      "created_at": "2026-10-05T09:30:00.000Z",
      "updated_at": "2026-10-05T09:30:02.871Z",
      "sent_at": "2026-10-05T09:30:01.210Z",
      "delivered_at": "2026-10-05T09:30:02.871Z",
      "read_at": null,
      "failed_at": null
    }
  }
}