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.

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 with the same key return the same result for a period of up to 12 hours.

Please note that idempotency is only supported for POST requests.