latestOpenAPI 3.1.02026-08-211286041.7 MB

b0c8a1820333

Message

Create Message

Creates a new message and dispatches it to all of the application's endpoints.

The eventId is an optional custom unique ID. It's verified to be unique only up to a day, after that no verification will be made. If a message with the same eventId already exists for the application, a 409 conflict error will be returned.

The eventType indicates the type and schema of the event. All messages of a certain eventType are expected to have the same schema. Endpoints can choose to only listen to specific event types. Messages can also have channels, which similar to event types let endpoints filter by them. Unlike event types, messages can have multiple channels, and channels don't imply a specific message content or schema.

The payload property is the webhook's body (the actual webhook message). Svix supports payload sizes of up to 1MiB, though it's generally a good idea to keep webhook payloads small, probably no larger than 40kb.

post/api/v1/app/{app_id}/msg

Path parameters

app_idstring required

The Application's ID or UID.

Example:unique-identifier

The Application's ID or UID.

Query parameters

with_contentboolean

When true, message payloads are included in the response.

Defaults to false in v2+ of the Svix SDKs, true in v1 or when manually making a request without specifying this parameter.

When true, message payloads are included in the response.

Defaults to false in v2+ of the Svix SDKs, true in v1 or when manually making a request without specifying this parameter.

Headers

idempotency-keystring

The request's idempotency key

Request body

channelsstring[] nullable

List of free-form identifiers that endpoints can filter by

deliverAtstring date-time nullable

The date and time at which the message will be delivered.

Note that this time is best-effort-only. Must be at least one minute and no more than 24 hours in the future.

eventIdstring nullable

Optional unique identifier for the message

eventTypestring required

The event type's name

payloadobject required

JSON payload to send as the request body of the webhook.

We also support sending non-JSON payloads. Please contact us for more information.

payloadRetentionHoursinteger nullable

Optional number of hours to retain the message payload. Note that this is mutually exclusive with payloadRetentionPeriod.

payloadRetentionPeriodinteger nullable

Optional number of days to retain the message payload. Defaults to 90. Note that this is mutually exclusive with payloadRetentionHours.

tagsstring[] nullable

List of free-form tags that can be filtered by when listing messages

transformationsParamsobject nullable

Extra parameters to pass to Transformations (for future use)

Example request

{
  "application": {
    "name": "My first application",
    "uid": "unique-identifier"
  },
  "channels": [
    "project_123",
    "group_2"
  ],
  "eventId": "unique-identifier",
  "eventType": "user.signup",
  "payload": {
    "type": "user.created",
    "email": "test@example.com",
    "username": "test_user"
  },
  "payloadRetentionPeriod": 90,
  "tags": [
    "my_tag",
    "other"
  ]
}

Response

channelsstring[] nullable

List of free-form identifiers that endpoints can filter by

deliverAtstring date-time nullable

eventIdstring nullable

Optional unique identifier for the message

eventTypestring required

The event type's name

idstring required

The Message's ID.

payloadobject required

tagsstring[] nullable

timestampstring date-time required

Example response

{
  "channels": [
    "project_123",
    "group_2"
  ],
  "eventId": "unique-identifier",
  "eventType": "user.signup",
  "id": "msg_1srOrx2ZWZBpBUvZwXKQmoEYga2",
  "payload": {
    "type": "user.created",
    "email": "test@example.com",
    "username": "test_user"
  },
  "tags": [
    "project_1337"
  ]
}