Set webhook URL
Bearer ds_live_ / ds_test_PUT
/api/v1/merchant/webhookSaves (and re-enables) your webhook URL. Before saving we send a signed webhook.verify event to it; any 2xx answer passes. A signing secret is generated the first time — store it, because it is only returned once.
Language
curl -X PUT "https://finaldatasub.com/api/v1/merchant/webhook" \
-H "Authorization: Bearer ds_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"url": "https://example.com/webhooks/vtu"
}'Authentication
Send your secret API key in the header. Authorization: Token … and X-API-Key: … are also accepted.
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer ds_live_YOUR_KEY | Yes |
| Content-Type | application/json | Yes |
| Accept | application/json | Recommended |
Authentication failures (401 UNAUTHORIZED, 403 IP_NOT_ALLOWED / ACCOUNT_SUSPENDED / API_ACCESS_NOT_APPROVED, 429 RATE_LIMITED) are listed in Authentication.
Parameters
Responses
200 OK — New secret · 200 OK — Updated · 400 Bad Request — Unreachable
{
"status": "successful",
"webhook": {
"url": "https://example.com/webhooks/vtu",
"is_active": true,
"secret_hint": "whsec_…9f3a",
"signature_header": "X-Datason-Signature",
"last_success_at": null,
"last_failure_at": null
},
"secret": "whsec_4f1c0b7a2e9d48b6a1c3e5f7d9b29f3a",
"message": "Store this secret now; it will not be shown again."
}Errors
Errors specific to this endpoint, in addition to the authentication and validation errors common to every request.
| Code | HTTP | When |
|---|---|---|
| INVALID_URL | 400 | Not a valid URL, not HTTPS, or the host resolves to a private / reserved IP. |
| WEBHOOK_UNREACHABLE | 400 | The webhook.verify probe did not get a 2xx response. |
Notes
secretis null on later updates unless you sendrotate_secret: true.