Sign in

v2

latestOpenAPI 3.1.02026-07-312303692.4 MB
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.

When true, message payloads are included in the response.

Headers

idempotency-keystring

The request's idempotency key

Request body

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.

channelsstring[] nullable

List of free-form identifiers that endpoints can filter by

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)

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.

payloadRetentionPeriodinteger nullable

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

payloadRetentionHoursinteger nullable

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

Example request

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

Response

eventIdstring nullable

Optional unique identifier for the message

eventTypestring required

The event type's name

payloadobject required
channelsstring[] nullable

List of free-form identifiers that endpoints can filter by

idstring required

The Message's ID.

timestampstring date-time required
tagsstring[] nullable
deliverAtstring date-time nullable

Example response

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