API Reference / Webhooks REST

Actions

Re-sends the payload of an earlier delivery to the webhook URL you have configured today. Use it to recover events your endpoint missed during an outage.

What is re-sent: The stored payload, byte for byte — same eventType, same timestamp, same transaction snapshot as the original. Conomy does not rebuild it from current state, so a replayed event describes the transaction as it was when the event fired, not as it is now. Read the transaction if you need its current state.

Where it is sent: To your CURRENT webhookUrl, signed with your CURRENT secretKey — not the ones in force when the original was sent. The intent is to reach where you are listening today. The X-Webhook-Signature header is recomputed over the replayed body, so verify it exactly as you verify a first delivery.

How to recognise a replay: The request carries the X-Webhook-Replay-Of header holding the ID of the original delivery. Because the body is byte-identical to the one already sent, that header and the payload itself are the two handles you have for deduplication — the payload contains no separate event ID.

Your receiver MUST be idempotent: A replay can deliver an event your endpoint already processed, because the original may have reached you and failed only on the way back. Key your processing on transaction.id together with eventType and make reprocessing a no-op. A replayed event must never credit an account, release goods or notify a user twice.

Replayable states: failed and skipped deliveries can be replayed freely. A delivered delivery already reached your endpoint, so replaying it is the case that can duplicate work on your side: it requires force: true in the body, and without it the call returns 409 Conflict with the current status in the error details.

The original is never modified: A replay inserts a NEW delivery row with isReplay: true and replayOf set to the original ID, and returns that new row. The original keeps its own outcome forever, so the log stays a truthful history of every attempt.

Audit trail: Each replay is its own row — createdAt records when it was requested, replayOf which delivery it repeats, and requestedBy who asked for it.

Rate limit: Approximately 6 replays per minute per merchant, with short bursts of up to 10. Exceeding it returns 429 Too Many Requests with a Retry-After header; wait that many seconds instead of retrying immediately.

Not enforced yet: force, requestedBy and the 409 Conflict response are the agreed contract but are not live — today a replay is accepted whatever the original's status, and no actor is recorded. Until they ship, prevent replays of delivered deliveries in your own tooling and do not rely on requestedBy being present on a row.

POST/v1/notifications/{id}/replay

Replay a notification delivery

Headers

Authorizationstringrequired

Bearer access token returned by the authentication endpoint.

conomyhq-api-versionstring

API version selector for Conomy endpoints. Use 24-04-2025 for the current version.

Path parameters

idstringrequired

The ID of the delivery to replay.

Request body

Optional. Omitting the body is equivalent to force: false.

forceboolean

Required to replay a delivery whose status is already delivered. Setting it acknowledges that your endpoint will receive an event it has already accepted.

Defaultfalse

requestedBystring

Identifier of the operator or system requesting the replay, recorded on the new delivery row for audit.

Responses

200The replay was attempted and a new delivery row was created. Read its status for the outcome — delivered if your endpoint accepted it, failed if it did not, skipped if you have no webhook URL configured. A failed replay is itself replayable.

idstringrequired

Unique ID of this delivery. Pass it to the get and replay operations.

Example68a1b2c3d4e5f6a7b8c9d0e1

createdAtstringdate-timerequired

When this attempt was made.

Example2026-08-01T12:00:05.412Z

identityIdstring

The identity the notified transaction belongs to.

Example67a02f34ad9aa801a60144ea

transactionIdstring

The transaction the event is about.

Example67a0307eaddea901a60144ec

eventTypestring

The event name that was sent. Same values as the eventType field of the webhook-transaction-event payload.

Examplepayment.received

reasonstring

Raw discriminator that produced the eventType, for example settled or refundCreated.

Examplereceived

statusstringrequired

deliveredfailedskipped

httpStatusintegerrequired

HTTP status your endpoint returned, or 0 when the request never completed — a timeout, DNS or TLS failure.

Example502

attemptsintegerrequired

How many HTTP requests this single delivery row represents.

Example1

targetHoststring

Host the request was sent to. Only the host is recorded, never the full URL, path or query string.

Examplehooks.merchant.com

testModebooleanrequired

Whether this delivery originated in the sandbox environment.

Examplefalse

isReplaybooleanrequired

True when this row was produced by the replay operation.

Examplefalse

replayOfstring

ID of the delivery this row repeats. Present only when isReplay is true. The same value is sent to your endpoint as the X-Webhook-Replay-Of header, which is how you deduplicate a replay.

Example68a1b2c3d4e5f6a7b8c9d0e1

requestedBystring

Who requested the replay. Not populated yet — the audit row currently records when (createdAt) and which (replayOf) but no actor. Treat it as absent until that ships.

Exampleops:felipe@conomyhq.com

payloadobjectshow 5 properties

Webhook payload sent by Conomy to the client URL.

responseBodyExcerptstring

First 500 characters of your endpoint's response body, kept for diagnosis. Truncated, never the full body.

Example{"ok":true}

errorMessagestring

Transport-level error when the request never reached your endpoint. Absent when the request completed.

ExamplePost "https://hooks.merchant.com/conomy"…

401Missing or invalid authentication token.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

404No delivery with this ID is visible to your credential — either it does not exist, or it belongs to another merchant.

errorstring

Examplenot found

409The delivery already reached your endpoint and force was not set. The error.info.currentStatus field contains the actual current status.

errorobjectshow 2 properties

messagenull

429Replay rate limit exceeded for this merchant.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

500Unexpected internal server error.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

CodeTry it Workbench

Request

HTTPcurlTypeScriptPythonGoRust

POST /sandbox/v1/notifications/{id}/replay HTTP/1.1
Host: api.conomyhq.com
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
Content-Type: application/json

{
  "force": false,
  "requestedBy": "ops:felipe@conomyhq.com"
}

curl -X POST \
  'https://api.conomyhq.com/sandbox/v1/notifications/{id}/replay' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'Content-Type: application/json' \
  -d '{
    "force": false,
    "requestedBy": "ops:felipe@conomyhq.com"
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/v1/notifications/{id}/replay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "force": false,
    "requestedBy": "ops:felipe@conomyhq.com"
  }),
});

const data = await response.json();

import requests

payload = {
    "force": false,
    "requestedBy": "ops:felipe@conomyhq.com"
}

response = requests.post(
    'https://api.conomyhq.com/sandbox/v1/notifications/{id}/replay',
    headers={
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'Content-Type': 'application/json',
    },
    json=payload
)

data = response.json()

package main

import (
	"encoding/json"
	"net/http"
	"bytes"
)

func main() {
	payload, _ := json.Marshal(	{
	  "force": false,
	  "requestedBy": "ops:felipe@conomyhq.com"
	})
	body := bytes.NewBuffer(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/v1/notifications/{id}/replay", body)
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let resp = client
        .post("https://api.conomyhq.com/sandbox/v1/notifications/{id}/replay")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("Content-Type", "application/json")
        .json(&json!({
        "force": false,
        "requestedBy": "ops:felipe@conomyhq.com"
}))
        .send()
        .await?;

    let data: serde_json::Value = resp.json().await?;
    Ok(())
}

Response

200 404 409 400 401 403 422 500

{
  "id": "68a1b2c3d4e5f6a7b8c9d0e1",
  "createdAt": "2026-08-01T12:00:05.412Z",
  "identityId": "67a02f34ad9aa801a60144ea",
  "transactionId": "67a0307eaddea901a60144ec",
  "eventType": "payment.received",
  "reason": "received",
  "status": "delivered",
  "httpStatus": 502,
  "attempts": 1,
  "targetHost": "hooks.merchant.com"
}

{
  "error": "not found"
}

{
  "error": {},
  "message": {}
}

{
  "error": {
    "type": "bad_request",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "unauthorized",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "forbidden",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "validation_error",
    "info": {
      "field": "string",
      "message": "string"
    }
  },
  "message": null
}

{
  "error": {
    "type": "internal_error",
    "info": null
  },
  "message": null
}

Requestsandbox

Authentication

Bearer token*

Path parameters

id*

Body

jsonFormat

{ "force": false, "requestedBy": "ops:felipe@conomyhq.com" }

Send →