curl -X POST https://api.tracklysms.com/api/v2/webhooks \
-H "X-Api-Key: trk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://hooks.bizinga.com/trackly", "events": ["message.delivered", "message.failed"] }'
import requests
resp = requests.post(
"https://api.tracklysms.com/api/v2/webhooks",
headers={"X-Api-Key": "trk_your_api_key"},
json={"url": "https://hooks.bizinga.com/trackly", "events": ["message.delivered", "message.failed"]},
)
print(resp.json()["signingSecret"]) # store this
{
"id": "66b0f7c84a1d4b2e9c3a1f2e",
"accountId": 1042,
"url": "https://hooks.bizinga.com/trackly",
"events": ["message.delivered", "message.failed"],
"active": true,
"signingSecretRotatedAt": null,
"createdAt": "2026-07-26T14:03:11Z",
"updatedAt": "2026-07-26T14:03:11Z",
"signingSecret": "9f2c...64hex",
"previousSigningSecret": null
}
Webhooks (v2)
Create Webhook Endpoint
Register an account-level HTTPS endpoint to receive signed webhook events.
POST
/
v2
/
webhooks
curl -X POST https://api.tracklysms.com/api/v2/webhooks \
-H "X-Api-Key: trk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://hooks.bizinga.com/trackly", "events": ["message.delivered", "message.failed"] }'
import requests
resp = requests.post(
"https://api.tracklysms.com/api/v2/webhooks",
headers={"X-Api-Key": "trk_your_api_key"},
json={"url": "https://hooks.bizinga.com/trackly", "events": ["message.delivered", "message.failed"]},
)
print(resp.json()["signingSecret"]) # store this
{
"id": "66b0f7c84a1d4b2e9c3a1f2e",
"accountId": 1042,
"url": "https://hooks.bizinga.com/trackly",
"events": ["message.delivered", "message.failed"],
"active": true,
"signingSecretRotatedAt": null,
"createdAt": "2026-07-26T14:03:11Z",
"updatedAt": "2026-07-26T14:03:11Z",
"signingSecret": "9f2c...64hex",
"previousSigningSecret": null
}
Registers an HTTPS endpoint to receive signed events. An account may have up to 20 endpoints. The response includes the signing secret — returned here (and on rotation) — which you store to verify signatures.
These are the partner webhook control plane endpoints (HMAC-signed, retried, replayable). They are distinct from the per-list Delivery Forwarding webhooks configured in the dashboard.
Body Parameters
string
required
An
https:// URL, max 2000 characters, resolving to a public host (private/loopback addresses are rejected).array
required
A non-empty list of event types to subscribe to — any of the message events (
message.delivered, message.failed, message.reply, contact.opted_out) or business-profile events (business_profile.verified, business_profile.rejected, business_profile.name_confirm_required, business_profile.review_required).Examples
curl -X POST https://api.tracklysms.com/api/v2/webhooks \
-H "X-Api-Key: trk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://hooks.bizinga.com/trackly", "events": ["message.delivered", "message.failed"] }'
import requests
resp = requests.post(
"https://api.tracklysms.com/api/v2/webhooks",
headers={"X-Api-Key": "trk_your_api_key"},
json={"url": "https://hooks.bizinga.com/trackly", "events": ["message.delivered", "message.failed"]},
)
print(resp.json()["signingSecret"]) # store this
{
"id": "66b0f7c84a1d4b2e9c3a1f2e",
"accountId": 1042,
"url": "https://hooks.bizinga.com/trackly",
"events": ["message.delivered", "message.failed"],
"active": true,
"signingSecretRotatedAt": null,
"createdAt": "2026-07-26T14:03:11Z",
"updatedAt": "2026-07-26T14:03:11Z",
"signingSecret": "9f2c...64hex",
"previousSigningSecret": null
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | validation_failed | The URL or events list is invalid. |
| 409 | quota_exceeded | The account already has 20 endpoints. |
Next Steps
Verify signatures
Validate the HMAC on every event.
List endpoints
See all endpoints on the account.