YourSendYourSend
Sign InGet Started →

Webhooks API

Register webhook endpoints to receive real-time notifications about message events.

GET /v1/webhooks

List all registered webhook endpoints.

cURL
curl https://api.yoursend.dev/v1/webhooks \
  -H "Authorization: Bearer ys_live_..."
Response
{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://example.com/webhooks/yoursend",
      "events": ["verified", "failed", "expired"],
      "is_active": true,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

POST /v1/webhooks

Register a new webhook endpoint. Returns the HMAC signing secret — store it securely.

FieldTypeRequiredDescription
urlstringYesHTTPS endpoint URL
eventsstring[]NoEvents to subscribe to (default: verified, failed, expired)
cURL
curl -X POST https://api.yoursend.dev/v1/webhooks \
  -H "Authorization: Bearer ys_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/yoursend",
    "events": ["verified", "sent", "delivered", "failed"]
  }'
Response (201)
{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/yoursend",
  "events": ["verified", "sent", "delivered", "failed"],
  "is_active": true,
  "secret": "whsec_a1b2c3d4e5f6...",
  "created_at": "2025-01-01T00:00:00Z"
}

Important: The secret is only returned once at creation. Store it securely to verify webhook signatures.

DELETE /v1/webhooks/:id

Delete a webhook endpoint.

cURL
curl -X DELETE https://api.yoursend.dev/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer ys_live_..."

Webhook Events

EventDescription
sentMessage was accepted for delivery
deliveredMessage was successfully delivered
verifiedOTP code was successfully verified
failedMessage delivery failed or OTP max attempts exceeded
expiredOTP verification expired before being verified