Delivery webhooks

Configure an endpoint

From an owner session, call PUT /delivery-webhook with a public HTTPS URL on port 443. Textly returns a signing secret once. Store it securely; configuring the endpoint again rotates the secret.

PUT /delivery-webhook
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{ "url": "https://your-app.example/webhooks/textly" }

Use GET /delivery-webhook to view the configured URL, or DELETE /delivery-webhook to remove it. Your endpoint must accept a JSON POST and respond with any 2xx status.

Event payload

Textly currently sends message.accepted, message.delivered, message.failed, and message.rejected. The event ID stays the same across retries.

{
  "id": "event-uuid",
  "type": "message.delivered",
  "createdAt": "2026-10-06T12:00:00.000Z",
  "data": {
    "messageId": "message-uuid",
    "recipient": "254712345678",
    "providerMessageId": "provider-message-id",
    "status": "delivered"
  }
}

Verify the signature

Read the raw request body. Compute HMAC-SHA256 with your signing secret over <X-Textly-Timestamp>.<raw body> and compare it to the hex value in X-Textly-Signature. Use a constant-time comparison, reject old timestamps, and deduplicate on X-Textly-Event-Id.

const signed = `${timestamp}.${rawBody}`;
const expected = createHmac('sha256', signingSecret)
  .update(signed)
  .digest('hex');

// Compare expected with the hex value after "sha256=".
// Keep the raw body exactly as received.

Retries and delivery order

Textly gives your endpoint ten seconds to respond. Network failures and non-2xx responses retry with backoff, up to eight attempts. Delivery can happen more than once and events may arrive out of order, so your receiver should use the event ID and message ID rather than assuming sequence.