Delivery and retries

Octane makes up to 3 attempts per delivery, each with a 500 ms timeout, and switches the webhook off after 50 consecutive failures or 3 days of failure. The delivery id is the same on every attempt, so de-duplicate on it.

A single deliveryCopy Anchor Link

For each transaction and each of your keys that has a webhook URL, Octane makes one delivery:

The timeout is deliberately short. Your handler must not do any work before responding: no database writes, no downstream API calls, no image downloads. The only things to do inline are verifying the signature and handing the raw event to a queue or background job, then returning 2xx.

How often does Octane retry?Copy Anchor Link

A failed delivery is retried up to 3 attempts in total, spaced roughly as follows:

Every attempt sends the same body and the same delivery id; only the signature timestamp and the image URLs (re-signed, 24-hour validity) change.

After the third failed attempt the delivery is recorded as failed on Octane's side, together with the response your endpoint returned. Octane can redeliver a failed event on request. A redelivery carries the original id.

When is a webhook disabled?Copy Anchor Link

If deliveries keep failing, the webhook is switched off automatically after 50 consecutive failed deliveries or 3 days of continuous failure, whichever comes first. You and Octane Operations are notified by email.

• Any successful delivery resets the failure counter.
• While disabled, no events are sent and none are queued. Use the Pull API to backfill the gap once your endpoint is healthy.
• Ask Octane to re-enable the webhook when the endpoint is fixed.

IdempotencyCopy Anchor Link

Retries and redeliveries mean your endpoint can receive the same event more than once. The delivery id (also in X-Octane-Delivery) is deterministic for a given transaction and key, so it is a safe idempotency key:

async function handle(event) {
  const inserted = await db.execute(
    'INSERT INTO octane_events (delivery_id, received_at) VALUES ($1, now()) ON CONFLICT DO NOTHING',
    [event.id],
  );
  if (inserted.rowCount === 0) return; // already processed

  await processTransaction(event.data.transaction);
}

Alternatively, upsert on data.transaction.id: a transaction is only ever pushed once per key, so a second delivery with the same transaction id is always a retry.

Are events delivered in order?Copy Anchor Link

Events are delivered as transactions are confirmed, but ordering across events is not guaranteed, especially when retries are involved. Use data.transaction.created_at or confirmed_at if order matters to you.

Monitoring on your sideCopy Anchor Link

• Alert on a sustained rate of signature failures: it usually means a rotated secret or a misconfigured raw-body handler.
• Alert if you have received no events for longer than your usual traffic pattern; the webhook may have been disabled.
• Log the delivery id with every processed event so support conversations can reference it.
• Reconcile daily with the Pull API to catch anything missed while your endpoint was down.