API Reference / Webhooks REST

Actions

Payload Conomy sends to your configured webhook URL when a transaction status changes. This callback is delivered to your application, not called by your backend against the Conomy API. Verify the signature before processing the event.

POST/client-url

Transaction status webhook

Request body required

Signed transaction status event delivered to the client webhook URL.

eventstringrequired

Transaction.CapturedTransaction.ReceivedTransaction.Failed

dataobjectrequired

Event payload.

transactionobjectrequiredshow 6 properties

Transaction snapshot included in a webhook delivery.

signaturestringmin 64 charsmax 64 chars/^[a-f0-9]{64}$/required

HMAC-SHA256 hexadecimal digest computed from the full JSON body without this signature field, using the configured webhook secret.

Responses

200Return any 2xx response after accepting the event. The response body is ignored.

Request

HTTPcurlTypeScriptPythonGoRust

POST /webhooks/conomy HTTP/1.1
Host: yourapp.com
Content-Type: application/json

{
  "event": "Transaction.Captured",
  "data": {
    "transaction": {
      "id": "67a0307eaddea901a60144ec",
      "purchaseAmount": "50000",
      "totalAmount": "50000",
      "externalId": "{{CLIENT_TRANSACTION_ID}}",
      "currency": "COP",
      "status": "CAPTURED"
    }
  },
  "signature": "f8a23d5e0c7c2b6e4a8f9d0c5b3d7e1a7f6c4e2d9b0a5f8c3e1d6b9a7c4e2d1f"
}

curl -X POST \
  'https://yourapp.com/webhooks/conomy' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "Transaction.Captured",
    "data": {
      "transaction": {
        "id": "67a0307eaddea901a60144ec",
        "purchaseAmount": "50000",
        "totalAmount": "50000",
        "externalId": "{{CLIENT_TRANSACTION_ID}}",
        "currency": "COP",
        "status": "CAPTURED"
      }
    },
    "signature": "f8a23d5e0c7c2b6e4a8f9d0c5b3d7e1a7f6c4e2d9b0a5f8c3e1d6b9a7c4e2d1f"
  }'

const response = await fetch('https://yourapp.com/webhooks/conomy', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "event": "Transaction.Captured",
    "data": {
      "transaction": {
        "id": "67a0307eaddea901a60144ec",
        "purchaseAmount": "50000",
        "totalAmount": "50000",
        "externalId": "{{CLIENT_TRANSACTION_ID}}",
        "currency": "COP",
        "status": "CAPTURED"
      }
    },
    "signature": "f8a23d5e0c7c2b6e4a8f9d0c5b3d7e1a7f6c4e2d9b0a5f8c3e1d6b9a7c4e2d1f"
  }),
});

const data = await response.json();

import requests

payload = {
    "event": "Transaction.Captured",
    "data": {
        "transaction": {
            "id": "67a0307eaddea901a60144ec",
            "purchaseAmount": "50000",
            "totalAmount": "50000",
            "externalId": "{{CLIENT_TRANSACTION_ID}}",
            "currency": "COP",
            "status": "CAPTURED"
        }
    },
    "signature": "f8a23d5e0c7c2b6e4a8f9d0c5b3d7e1a7f6c4e2d9b0a5f8c3e1d6b9a7c4e2d1f"
}

response = requests.post(
    'https://yourapp.com/webhooks/conomy',
    headers={
    'Content-Type': 'application/json',
    },
    json=payload
)

data = response.json()

package main

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

func main() {
	payload, _ := json.Marshal(	{
	  "event": "Transaction.Captured",
	  "data": {
	    "transaction": {
	      "id": "67a0307eaddea901a60144ec",
	      "purchaseAmount": "50000",
	      "totalAmount": "50000",
	      "externalId": "{{CLIENT_TRANSACTION_ID}}",
	      "currency": "COP",
	      "status": "CAPTURED"
	    }
	  },
	  "signature": "f8a23d5e0c7c2b6e4a8f9d0c5b3d7e1a7f6c4e2d9b0a5f8c3e1d6b9a7c4e2d1f"
	})
	body := bytes.NewBuffer(payload)
	req, _ := http.NewRequest("POST", "https://yourapp.com/webhooks/conomy", body)
	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://yourapp.com/webhooks/conomy")
        .header("Content-Type", "application/json")
        .json(&json!({
        "event": "Transaction.Captured",
        "data": {
                "transaction": {
                        "id": "67a0307eaddea901a60144ec",
                        "purchaseAmount": "50000",
                        "totalAmount": "50000",
                        "externalId": "{{CLIENT_TRANSACTION_ID}}",
                        "currency": "COP",
                        "status": "CAPTURED"
                }
        },
        "signature": "f8a23d5e0c7c2b6e4a8f9d0c5b3d7e1a7f6c4e2d9b0a5f8c3e1d6b9a7c4e2d1f"
}))
        .send()
        .await?;

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

Response

400 401 403 404 422 500

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

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

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

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

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

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