Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orkesta.com.tr/llms.txt

Use this file to discover all available pages before exploring further.

Orkesta webhooks deliver HTTP POST requests to a URL you control whenever a payment event occurs in your workspace. Use webhooks for real-time automation — triggering ERP updates, sending notifications, or kicking off approval workflows.

​
Set up a webhook endpoint

1

Create your endpoint URL

Your endpoint must be a publicly accessible HTTPS URL. It must return a 2xx status code within 10 seconds of receiving a request.
Acknowledge the request immediately and process the payload asynchronously. For long-running tasks (database writes, third-party calls), queue the work and respond with 200 OK right away.
2

Register the endpoint

  1. Go to Integrations → Webhooks.
  2. Click Add endpoint.
  3. Enter your HTTPS URL.
  4. Add an optional description to identify the endpoint later.
  5. Click Create.
3

Select events

After creating the endpoint, click Add events on the endpoint detail page. Subscribe to specific event types or choose All events.
Event typeTriggered when
payment.createdA new payment is created
payment.approvedA payment passes the approval workflow
payment.processingA payment is submitted to the bank for processing
payment.settledA payment is confirmed as settled
payment.failedA payment attempt fails
payment.cancelledA payment is cancelled before processing
reconciliation.completedA reconciliation run finishes
4

Verify the signature

Every webhook request includes an X-Signature-256 header. The value is an HMAC-SHA256 signature of the raw request body, signed with your endpoint secret. Always verify the signature before processing the payload.
import hmac
import hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)
Your endpoint secret is shown only once at creation. Save it securely. Rotate it at Integrations → Webhooks → [Endpoint] → Rotate secret if it is ever compromised.
5

Test with a sample payload

  1. Open the endpoint detail page.
  2. Click Send test event.
  3. Select an event type from the dropdown.
  4. Click Send.
The response status code and body appear in the test log beneath the button. Use this to confirm your endpoint receives and acknowledges requests correctly before going live.

​
Retry policy

Orkesta retries failed deliveries up to 5 times using exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, and 8 hours after the initial failure. If all five retries fail, the endpoint is automatically disabled. Re-enable it from Integrations → Webhooks once the issue is resolved.

​
Webhook payload structure

Every webhook request sends a JSON body with a consistent envelope. Below is an example payload for a payment.settled event:
payment.settled example
{
  "id": "evt_01hx4kqz9mf3r7t8v2wn5p6b",
  "type": "payment.settled",
  "created_at": "2026-05-20T14:32:10Z",
  "workspace_id": "ws_01hwk3nm7cg5p8q2d4rb9s0a",
  "data": {
    "payment": {
      "id": "pay_01hx4kmn8zr6q9w3t5vy7c2d",
      "status": "settled",
      "amount": 125000,
      "currency": "TRY",
      "reference": "INV-2026-00487",
      "description": "Supplier invoice payment — May 2026",
      "created_at": "2026-05-20T09:15:00Z",
      "settled_at": "2026-05-20T14:32:08Z",
      "bank": {
        "id": "bank_garanti",
        "name": "Garanti BBVA"
      },
      "metadata": {
        "erp_document_id": "FI-DOC-9981"
      }
    }
  }
}