Idempotency

Svix supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.

info

This section is about making API calls to Svix. For information on helping your customers ensure they only get a message once, please refer to receiving idempotency section (deduplication) below.

To perform an idempotent request, pass the idempotency key in the Idempotency-Key header to the request. The idempotency key should be a unique value generated by the client. You can create the key in however way you like, though we suggest using UUID v4, or any other string with enough entropy to avoid collisions.

JavaScript

const svix = new Svix("AUTH_TOKEN");
const message = {
  eventType: "invoice.paid",
  eventId: "evt_Wqb1k73rXprtTm7Qdlr38G",
  payload: {
    type: "invoice.paid",
    id: "invoice_WF7WtCLFFtd8ubcTgboSFNql",
    status: "paid",
    attempt: 2,
  },
};
await svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", message, {
    idempotencyKey: "fd56a56b-838d-4456-8b83-390802672895",
});

Python

svix = Svix("AUTH_TOKEN")
message = MessageIn(
    event_type="invoice.paid",
    event_id="evt_Wqb1k73rXprtTm7Qdlr38G",
    payload={
        "type": "invoice.paid",
        "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        "status": "paid",
        "attempt": 2
    }
)
svix.message.create(
    "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    message,
    PostOptions(idempotency_key="fd56a56b-838d-4456-8b83-390802672895")
)

Rust

svixClient := svix.New("AUTH_TOKEN", nil)
eventId := "evt_Wqb1k73rXprtTm7Qdlr38G"
message := svix.MessageIn{
    EventType: "invoice.paid",
    EventId: *svix.NullableString(&eventId),
    Payload: map[string]interface{}{
        "type":    "invoice.paid",
        "id":      "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        "status":  "paid",
        "attempt": 2,
    },
}
idempotencyKey := "fd56a56b-838d-4456-8b83-390802672895"
svixClient.Message.CreateWithOptions(ctx, "app_Xzx8bQeOB1D1XEYmAJaRGoj0", &message, &svix.PostOptions{
    IdempotencyKey: &idempotencyKey,
})

Go

let svix = Svix::new("AUTH_TOKEN".to_owned(), None);
svix.message()
    .create(
        "app_Xzx8bQeOB1D1XEYmAJaRGoj0".to_owned(),
        MessageIn {
            event_type: "invoice.paid".to_owned(),
            event_id: Some("evt_Wqb1k73rXprtTm7Qdlr38G".to_owned()),
            payload: json!({
                "type": "invoice.paid",
                "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
                "status": "paid",
                "attempt": 2
            }),
            ..MessageIn::default()
        },
        Some(PostOptions {
            idempotency_key: Some("fd56a56b-838d-4456-8b83-390802672895".to_owned()),
        }),
    )
    .await?;

Java

Svix svix = new Svix("AUTH_TOKEN");

MessageIn message = new MessageIn()
    .eventType("invoice.paid")
    .eventId("evt_Wqb1k73rXprtTm7Qdlr38G")
    .payload("{" +
        "\"type\": \"invoice.paid\"," +
        "\"id\": \"invoice_WF7WtCLFFtd8ubcTgboSFNql\"," +
        "\"status\": \"paid\"," +
        "\"attempt\": 2" +
    "}");

PostOptions opts = new PostOptions()
    .idempotencyKey("fd56a56b-838d-4456-8b83-390802672895");

svix.getMessage()
    .create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", message, opts);

Kotlin

val svix = Svix("AUTH_TOKEN")
svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    MessageIn(
        eventType = "invoice.paid",
        payload = mapOf<String, Any>(
            "type" to "invoice.paid",
            "id" to "invoice_WF7WtCLFFtd8ubcTgboSFNql",
            "status" to "paid",
            "attempt" to 2
        ),
        eventId = "evt_Wqb1k73rXprtTm7Qdlr38G"),
    PostOptions(
        idempotencyKey = "fd56a56b-838d-4456-8b83-390802672895"))

Ruby

svix = Svix::Client.new("AUTH_TOKEN")
svix.message.create(
    "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    Svix::MessageIn.new({
        "event_type" => "invoice.paid",
        "payload" => {
            "type": "invoice.paid",
            "id" => "invoice_WF7WtCLFFtd8ubcTgboSFNql",
            "status" => "paid",
            "attempt" => 2
        },
        "event_id" => "evt_Wqb1k73rXprtTm7Qdlr38G"}),
    { "idempotency_key" => "fd56a56b-838d-4456-8b83-390802672895" })

C#

var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
var message = new MessageIn(
    eventType: "invoice.paid",
    payload: new {
        type = "invoice.paid",
        id = "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        status = "paid",
        attempt = 2
    },
    eventId: "evt_Wqb1k73rXprtTm7Qdlr38G"
);
await svix.Message.CreateAsync(
    "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    message,
    null,
    "fd56a56b-838d-4456-8b83-390802672895"
);

PHP

Idempotency is not yet supported in the Svix CLI.

CLI

$svix = new Svix('AUTH_TOKEN');

$message = MessageIn::create(
  eventType: 'invoice.paid',
  payload: [
    'type' => 'invoice.paid',
    'id' => 'invoice_WF7WtCLFFtd8ubcTgboSFNql',
    'status' => 'paid',
    'attempt' => 2
  ]
)->withEventId('evt_Wqb1k73rXprtTm7Qdlr38G');

$svix->message->create(
  'app_Xzx8bQeOB1D1XEYmAJaRGoj0',
  $message,
  new MessageCreateOptions(idempotencyKey: 'fd56a56b-838d-4456-8b83-390802672895')
);

cURL

curl "https://api.us.svix.com/api/v1/app/app_Xzx8bQeOB1D1XEYmAJaRGoj0/msg/" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer AUTH_TOKEN" \
    -H "Idempotency-Key: fd56a56b-838d-4456-8b83-390802672895"
    -d '{ "eventType": "invoice.paid", "eventId": "evt_Wqb1k73rXprtTm7Qdlr38G", "payload": { "type": "event.type", "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql", "status": "paid", "attempt": 2 } }'

Svix's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key for any successful request. Subsequent requests using the same auth token and the same idempotency key will return the same result for a period of up to 12 hours.

Please note that idempotency is only supported for POST requests.

Receiving idempotency (deduplication)

Svix offers "at least once" delivery semantics. This means that if there are issues during delivery (e.g. networking issues) a message can sometimes be processed twice by the webhook receiver.

In many cases this is not a concern, and recipients can just process the duplicated requests. Though when "exactly once" semantics are required, webhook consumers can use Svix's webhook deduplication support to ensure that.

Svix includes a webhook-id header with every webhook request. That ID is unique per message but is reused across retries of the same message. Consumers can then use this identifier to ensure that they only process each event once, by for example storing the ID in redis with a 24hr expiry, and checking whether they already processed the message's webhook-id before processing it.