Skip to main content
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, 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

​
url
string
required
Webhook URL (must be HTTPS in production)
​
events
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), 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"]
  }'

​
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

​
id
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

​
id
string
required
The webhook ID

​
Request Body

​
url
string
New webhook URL (optional)
​
events
array
New array of event types (optional)
​
isActive
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

​
id
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

​
id
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.