Webhooks API

The Webhooks API allows you to create and manage webhooks that receive real-time notifications when escrow status changes, contracts are signed, cancellation requests are created, accepted, or rejected, a buyer rejects delivery, funds are added or refunded on an escrow, or identity verification status changes.

You can create a maximum of 2 webhooks per developer account. Choose your endpoints carefully.

Create Webhook

Create a new webhook endpoint to receive event notifications.

Request Body

string

required

Webhook URL (must be HTTPS in production)

array

Array of event types to subscribe to. Supported: escrow.status.updated, contract.signed, escrow.cancellation.requested, escrow.cancellation.rejected, escrow.cancellation.accepted, escrow.updated, escrow.deposit_proof.rejected (guest instant-escrow payment proof rejected by admin), escrow.delivery.rejected (buyer rejected delivery; includes optional reason), escrow.funds.added, escrow.funds.refunded (buyer add-funds / seller refund-funds adjustments), escrow.release_request.created, escrow.release_request.approved, escrow.release_request.auto_approved, escrow.release_request.disputed, escrow.release_request.resolved, escrow.release_request.released (per-period payouts on progressive-release escrows), escrow.balance.exhausted (no unreserved balance left; the escrow stays open for a top-up), identity.verification.updated (pre-account KYC approved or rejected), identity.verification.linked (KYC attached when user registers on DHMAD). Default: ["escrow.status.updated"]

Example Request

curl -X POST https://dhmad.tn/api/developer/webhooks \
  -H "Authorization: Bearer your_developer_token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/dhmad",
    "events": ["escrow.status.updated"]
  }'

const response = await fetch("https://dhmad.tn/api/developer/webhooks", {
  method: "POST",
  headers: {
    Authorization: "Bearer your_developer_token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/webhooks/dhmad",
    events: ["escrow.status.updated", "contract.signed"],
  }),
});

const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer your_developer_token',
    'Content-Type': 'application/json'
}

data = {
    'url': 'https://example.com/webhooks/dhmad',
    'events': ['escrow.status.updated', 'contract.signed']
}

response = requests.post(
    'https://dhmad.tn/api/developer/webhooks',
    json=data,
    headers=headers
)

data = response.json()

Example Response

{
  "message": "Webhook created successfully",
  "webhook": {
    "id": "507f1f77bcf86cd799439011",
    "url": "https://example.com/webhooks/dhmad",
    "secret": "a1b2c3d4e5f6...your_webhook_secret_hex",
    "events": ["escrow.status.updated", "contract.signed"],
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

The secret field is only returned when creating a webhook and when regenerating the secret. It is never included in list or get responses. Copy and store it immediately.

List Webhooks

Get all webhooks for your developer account.

Example Request

curl -X GET https://dhmad.tn/api/developer/webhooks \
  -H "Authorization: Bearer your_developer_token"

Example Response

{
  "webhooks": [
    {
      "id": "507f1f77bcf86cd799439011",
      "url": "https://example.com/webhooks/dhmad",
      "events": ["escrow.status.updated", "contract.signed"],
      "isActive": true,
      "lastTriggeredAt": "2024-01-15T10:30:00Z",
      "lastResponseStatus": 200,
      "failureCount": 0,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Get Webhook

Get details of a specific webhook.

Path Parameters

string

required

The webhook ID

Example Request

curl -X GET https://dhmad.tn/api/developer/webhooks/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer your_developer_token"

Update Webhook

Update a webhook’s URL, events, or active status.

Path Parameters

string

required

The webhook ID

Request Body

string

New webhook URL (optional)

array

New array of event types (optional)

boolean

Whether the webhook is active (optional)

Example Request

curl -X PUT https://dhmad.tn/api/developer/webhooks/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer your_developer_token" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Regenerate Secret

Generate a new signing secret for a webhook. The old secret will immediately stop working.

Path Parameters

string

required

The webhook ID

Example Request

curl -X POST https://dhmad.tn/api/developer/webhooks/507f1f77bcf86cd799439011/regenerate-secret \
  -H "Authorization: Bearer your_developer_token"

Example Response

{
  "message": "Webhook secret regenerated successfully",
  "secret": "e7f8a9b0c1d2...new_webhook_secret_hex"
}

The new secret is only shown in this response. Copy and store it immediately, then update your webhook handler to use the new secret for signature verification.

Delete Webhook

Delete a webhook permanently.

Path Parameters

string

required

The webhook ID

Example Request

curl -X DELETE https://dhmad.tn/api/developer/webhooks/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer your_developer_token"

Example Response

{
  "message": "Webhook deleted successfully"
}

Response Fields

Error Responses

400 Bad Request

Webhook Limit Reached

{
  "error": "Maximum 2 webhooks allowed per developer"
}

Invalid URL

{
  "error": "Invalid URL format"
}

HTTPS Required (Production)

{
  "error": "Only HTTPS URLs are allowed in production"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing developer token"
}

404 Not Found

{
  "error": "Webhook not found"
}

For detailed information about webhook events, payloads, and signature verification, see the Webhooks Guide.

Get Started

API Reference

Guides

Developer Portal

Create Webhook

Request Body

Example Request

Example Response

List Webhooks

Example Request

Example Response

Get Webhook

Path Parameters

Example Request

Update Webhook

Path Parameters

Request Body

Example Request

Regenerate Secret

Path Parameters

Example Request

Example Response

Delete Webhook

Path Parameters

Example Request

Example Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

​Create Webhook

​Request Body

​Example Request

​Example Response

​List Webhooks

​Example Request

​Example Response

​Get Webhook

​Path Parameters

​Example Request

​Update Webhook

​Path Parameters

​Request Body

​Example Request

​Regenerate Secret

​Path Parameters

​Example Request

​Example Response

​Delete Webhook

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​404 Not Found

Create Webhook

Request Body

Example Request

Example Response

List Webhooks

Example Request

Example Response

Get Webhook

Path Parameters

Example Request

Update Webhook

Path Parameters

Request Body

Example Request

Regenerate Secret

Path Parameters

Example Request

Example Response

Delete Webhook

Path Parameters

Example Request

Example Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found