Idempotent Requests

Our API supports idempotent requests to prevent the same operation from being performed twice. If you attempt an operation twice or more, it will process only the first attempt. For example, suppose a request to create a notification does not respond due to a network connection error. In that case, you can retry the request with the same idempotency key and it will create no additional notification.

To perform an idempotent request, you need to add an Idempotency-Key: <key> header on the request. An idempotency key is a unique value generated on your side, which the server uses to recognize subsequent retries of the same request. We suggest using V4 UUID to avoid collisions.

The resulting status code and body of the first request will be cached. Subsequent requests with the same idempotency key will return the same result. The cached results will expire after 24 hours.

curl https://api.magicbell.com/notifications \
  --request POST \
  --header 'X-MAGICBELL-API-KEY: MAGICBELL_API_KEY' \
  --header 'X-MAGICBELL-API-SECRET: MAGICBELL_API_SECRET' \
  --header 'IDEMPOTENCY-KEY: YOUR_IDEMPOTENCY_KEY' \
  --data '{
    "notification": {
        "title": "Task assigned to you: Upgrade to Startup plan",
        "content": "Hello, can you upgrade us to the Startup plan. Thank you.",
        "category": "billing",
        "action_url": "https://magicbell.com/pricing",
        "recipients": [
          { "email": "mary@example.com" },
          { "email": "richard@example.com" }
        ]
    }
  }'

Credit: https://stripe.com/docs/api/idempotent_requests