{
  "openapi": "3.0.3",
  "info": {
    "title": "Conerix API",
    "version": "1.0.0",
    "summary": "Production SMS API for sending, tracking, and managing messages at scale.",
    "description": "The Conerix REST API lets you send SMS messages, track delivery, manage sender IDs, configure webhooks, and rotate API keys from any HTTP-capable language.\n\nAll endpoints live under `/api/v1` and accept and return JSON. Authentication is via bearer API keys (see Authentication).",
    "contact": {
      "name": "Conerix Support",
      "url": "https://conerix.com/support",
      "email": "support@conerix.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://conerix.com/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {"name": "Messages", "description": "Send and retrieve SMS messages."},
    {"name": "Account", "description": "Account, balance, and usage."},
    {"name": "Senders", "description": "Manage sender IDs."},
    {"name": "API Keys", "description": "Create and rotate API keys."},
    {"name": "Webhooks", "description": "Configure webhook endpoints and inspect events."}
  ],
  "security": [{"BearerAuth": []}],
  "paths": {
    "/messages/send": {
      "post": {
        "tags": ["Messages"],
        "summary": "Send a single SMS",
        "description": "Dispatches one SMS through the optimal route for the destination, with automatic failover if the primary route is unavailable.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/SendMessageRequest"},
              "examples": {
                "basic": {
                  "summary": "Basic send",
                  "value": {
                    "to": "+12025550143",
                    "from": "Conerix",
                    "body": "Welcome to Conerix — your code is 482194."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message accepted for delivery.",
            "content": {
              "application/json": {"schema": {"$ref": "#/components/schemas/MessageEnvelope"}}
            }
          },
          "400": {"$ref": "#/components/responses/InvalidRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "402": {"$ref": "#/components/responses/InsufficientBalance"},
          "403": {"$ref": "#/components/responses/Forbidden"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/ServerError"}
        }
      }
    },
    "/messages/bulk": {
      "post": {
        "tags": ["Messages"],
        "summary": "Send a message to many recipients",
        "description": "Sends the same body to up to 1,000 recipients. Each recipient is sent as an individual message and reported back in the response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/BulkMessageRequest"}
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bulk send result.",
            "content": {
              "application/json": {"schema": {"$ref": "#/components/schemas/BulkResultEnvelope"}}
            }
          },
          "400": {"$ref": "#/components/responses/InvalidRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "402": {"$ref": "#/components/responses/InsufficientBalance"},
          "403": {"$ref": "#/components/responses/Forbidden"},
          "429": {"$ref": "#/components/responses/RateLimited"}
        }
      }
    },
    "/messages/{id}": {
      "get": {
        "tags": ["Messages"],
        "summary": "Retrieve a message",
        "parameters": [{"$ref": "#/components/parameters/MessageId"}],
        "responses": {
          "200": {
            "description": "The requested message.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MessageEnvelope"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      }
    },
    "/messages": {
      "get": {
        "tags": ["Messages"],
        "summary": "List messages",
        "parameters": [
          {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["pending","sent","delivered","failed","undelivered"]}},
          {"name": "to", "in": "query", "schema": {"type": "string"}},
          {"name": "created_after", "in": "query", "schema": {"type": "string", "format": "date-time"}},
          {"name": "created_before", "in": "query", "schema": {"type": "string", "format": "date-time"}},
          {"$ref": "#/components/parameters/Page"},
          {"$ref": "#/components/parameters/Limit"}
        ],
        "responses": {
          "200": {
            "description": "Paged list of messages.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MessageListEnvelope"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"}
        }
      }
    },
    "/account": {
      "get": {
        "tags": ["Account"],
        "summary": "Get the authenticated account",
        "responses": {
          "200": {
            "description": "Account details.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AccountEnvelope"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"}
        }
      }
    },
    "/balance": {
      "get": {
        "tags": ["Account"],
        "summary": "Get the current account balance",
        "responses": {
          "200": {
            "description": "Current balance.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BalanceEnvelope"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"}
        }
      }
    },
    "/usage": {
      "get": {
        "tags": ["Account"],
        "summary": "Get message usage statistics",
        "parameters": [
          {"name": "period", "in": "query", "schema": {"type": "string", "enum": ["day", "month", "all"], "default": "month"}}
        ],
        "responses": {
          "200": {
            "description": "Usage statistics.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/UsageEnvelope"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"}
        }
      }
    },
    "/senders": {
      "get": {
        "tags": ["Senders"],
        "summary": "List sender IDs",
        "parameters": [
          {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["pending","approved","rejected","suspended"]}},
          {"$ref": "#/components/parameters/Page"},
          {"$ref": "#/components/parameters/Limit"}
        ],
        "responses": {
          "200": {
            "description": "Paged list of senders.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SenderListEnvelope"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"}
        }
      }
    },
    "/senders/create": {
      "post": {
        "tags": ["Senders"],
        "summary": "Register a new sender ID",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateSenderRequest"}}}
        },
        "responses": {
          "201": {
            "description": "Sender created (pending approval).",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SenderEnvelope"}}}
          },
          "400": {"$ref": "#/components/responses/InvalidRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"}
        }
      }
    },
    "/senders/{id}": {
      "get": {
        "tags": ["Senders"],
        "summary": "Retrieve a sender",
        "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {
          "200": {
            "description": "Sender details.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SenderEnvelope"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      }
    },
    "/api-keys": {
      "get": {
        "tags": ["API Keys"],
        "summary": "List API keys",
        "responses": {
          "200": {
            "description": "List of API keys on this account.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKeyListEnvelope"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"}
        }
      }
    },
    "/api-keys/create": {
      "post": {
        "tags": ["API Keys"],
        "summary": "Create a new API key",
        "description": "The full plaintext key is returned **only once** in the response. Store it securely; it cannot be retrieved later.",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateApiKeyRequest"}}}
        },
        "responses": {
          "201": {
            "description": "API key created.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreatedApiKeyEnvelope"}}}
          },
          "400": {"$ref": "#/components/responses/InvalidRequest"},
          "403": {"$ref": "#/components/responses/Forbidden"}
        }
      }
    },
    "/api-keys/{id}": {
      "delete": {
        "tags": ["API Keys"],
        "summary": "Revoke an API key",
        "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {
          "200": {
            "description": "Key revoked.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeletedEnvelope"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      }
    },
    "/webhooks": {
      "get": {
        "tags": ["Webhooks"],
        "summary": "List webhook endpoints",
        "responses": {
          "200": {
            "description": "Webhook endpoints.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEndpointListEnvelope"}}}
          }
        }
      }
    },
    "/webhooks/create": {
      "post": {
        "tags": ["Webhooks"],
        "summary": "Create a webhook endpoint",
        "description": "The `signing_secret` is returned **only when created**. Use it to verify the `Conerix-Signature` header on incoming webhooks.",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateWebhookRequest"}}}
        },
        "responses": {
          "201": {
            "description": "Endpoint created.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEndpointWithSecretEnvelope"}}}
          }
        }
      }
    },
    "/webhooks/{id}": {
      "get": {
        "tags": ["Webhooks"],
        "summary": "Retrieve a webhook endpoint",
        "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {
          "200": {
            "description": "Webhook endpoint.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEndpointEnvelope"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      },
      "delete": {
        "tags": ["Webhooks"],
        "summary": "Delete a webhook endpoint",
        "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {
          "200": {
            "description": "Endpoint deleted.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeletedEnvelope"}}}
          }
        }
      }
    },
    "/events": {
      "get": {
        "tags": ["Webhooks"],
        "summary": "List webhook events",
        "parameters": [
          {"name": "type", "in": "query", "schema": {"type": "string", "enum": ["message.sent","message.delivered","message.failed"]}},
          {"$ref": "#/components/parameters/Page"},
          {"$ref": "#/components/parameters/Limit"}
        ],
        "responses": {
          "200": {
            "description": "Paged list of events.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EventListEnvelope"}}}
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "API key passed as `Authorization: Bearer <KEY>`. Keys start with `ds_live_`."
      }
    },
    "parameters": {
      "MessageId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {"type": "string", "example": "msg_VyB2pNkX0wnA9aTrLqDh1Z3Fc"}
      },
      "Page": {
        "name": "page",
        "in": "query",
        "schema": {"type": "integer", "minimum": 1, "default": 1}
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}
      }
    },
    "responses": {
      "InvalidRequest": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "Unauthorized": {"description": "Missing or invalid API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "Forbidden": {"description": "API key lacks required permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "NotFound": {"description": "Resource not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "InsufficientBalance": {"description": "Insufficient balance to send.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "RateLimited": {"description": "Rate limit exceeded.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "ServerError": {"description": "Internal server error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "properties": {
          "request_id": {"type": "string"},
          "api_version": {"type": "string", "example": "v1"}
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean", "example": false},
          "error": {
            "type": "object",
            "properties": {
              "type": {"type": "string", "enum": ["invalid_request_error","authentication_error","authorization_error","balance_error","rate_limit_error","provider_error","api_error"]},
              "code": {"type": "string", "example": "invalid_request"},
              "message": {"type": "string"},
              "param": {"type": "string"},
              "details": {"type": "object", "additionalProperties": true}
            }
          },
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "example": "msg_VyB2pNkX0wnA9aTrLqDh1Z3Fc"},
          "object": {"type": "string", "example": "message"},
          "to": {"type": "string"},
          "from": {"type": "string"},
          "body": {"type": "string"},
          "status": {"type": "string", "enum": ["pending","sent","delivered","failed","undelivered"]},
          "cost": {"type": "number", "format": "float"},
          "currency": {"type": "string", "example": "USD"},
          "route_id": {"type": "integer", "example": 12},
          "provider_message_id": {"type": "string"},
          "attempts": {"type": "integer"},
          "error": {
            "type": "object",
            "nullable": true,
            "properties": {
              "code": {"type": "string"},
              "message": {"type": "string"}
            }
          },
          "created_at": {"type": "string", "format": "date-time"},
          "sent_at": {"type": "string", "format": "date-time", "nullable": true},
          "delivered_at": {"type": "string", "format": "date-time", "nullable": true},
          "failed_at": {"type": "string", "format": "date-time", "nullable": true}
        }
      },
      "Sender": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "object": {"type": "string", "example": "sender"},
          "sender_id": {"type": "string"},
          "type": {"type": "string", "enum": ["alphanumeric","numeric","short_code","long_code"]},
          "country_code": {"type": "string", "nullable": true},
          "status": {"type": "string", "enum": ["pending","approved","rejected","suspended"]},
          "approved_at": {"type": "string", "format": "date-time", "nullable": true},
          "created_at": {"type": "string", "format": "date-time"}
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "object": {"type": "string", "example": "api_key"},
          "name": {"type": "string"},
          "key_hint": {"type": "string", "example": "ds_live_a1b2...c3d4"},
          "is_active": {"type": "boolean"},
          "permissions": {"type": "array", "items": {"type": "string"}},
          "rate_limit": {"type": "integer"},
          "last_used_at": {"type": "string", "format": "date-time", "nullable": true},
          "expires_at": {"type": "string", "format": "date-time", "nullable": true},
          "created_at": {"type": "string", "format": "date-time"}
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "object": {"type": "string", "example": "webhook_endpoint"},
          "url": {"type": "string", "format": "uri"},
          "description": {"type": "string", "nullable": true},
          "events": {"type": "array", "items": {"type": "string", "enum": ["message.sent","message.delivered","message.failed"]}},
          "is_active": {"type": "boolean"},
          "failure_count": {"type": "integer"},
          "last_success_at": {"type": "string", "format": "date-time", "nullable": true},
          "last_failure_at": {"type": "string", "format": "date-time", "nullable": true},
          "disabled_at": {"type": "string", "format": "date-time", "nullable": true},
          "created_at": {"type": "string", "format": "date-time"}
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "example": "evt_..."},
          "object": {"type": "string", "example": "event"},
          "type": {"type": "string", "enum": ["message.sent","message.delivered","message.failed"]},
          "created_at": {"type": "string", "format": "date-time"},
          "data": {"$ref": "#/components/schemas/Message"}
        }
      },
      "SendMessageRequest": {
        "type": "object",
        "required": ["to", "from", "body"],
        "properties": {
          "to": {"type": "string", "description": "E.164 phone number.", "example": "+12025550143"},
          "from": {"type": "string", "description": "Sender ID. Up to 11 alphanumeric or a numeric long code.", "example": "Conerix"},
          "body": {"type": "string", "maxLength": 1600},
          "route_id": {"type": "integer", "nullable": true},
          "route_id": {"type": "integer", "nullable": true, "description": "Optional route assigned to your account. Routing is managed by Conerix."},
          "reference": {"type": "string", "nullable": true, "description": "Your own correlation id."}
        }
      },
      "BulkMessageRequest": {
        "type": "object",
        "required": ["recipients", "from", "body"],
        "properties": {
          "recipients": {"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 1000},
          "from": {"type": "string"},
          "body": {"type": "string"},
          "route_id": {"type": "integer", "nullable": true},
          "route_id": {"type": "integer", "nullable": true, "description": "Optional route assigned to your account."}
        }
      },
      "CreateSenderRequest": {
        "type": "object",
        "required": ["sender_id"],
        "properties": {
          "sender_id": {"type": "string", "maxLength": 16},
          "type": {"type": "string", "enum": ["alphanumeric","numeric","short_code","long_code"]},
          "country_code": {"type": "string", "minLength": 2, "maxLength": 2}
        }
      },
      "CreateApiKeyRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {"type": "string"},
          "permissions": {"type": "array", "items": {"type": "string"}, "example": ["sms:send","sms:read"]},
          "rate_limit": {"type": "integer", "minimum": 1, "maximum": 6000},
          "daily_limit": {"type": "integer", "minimum": 1, "nullable": true},
          "monthly_limit": {"type": "integer", "minimum": 1, "nullable": true},
          "allowed_ips": {"type": "array", "items": {"type": "string"}, "nullable": true},
          "expires_at": {"type": "string", "format": "date-time", "nullable": true}
        }
      },
      "CreateWebhookRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": {"type": "string", "format": "uri"},
          "description": {"type": "string"},
          "events": {"type": "array", "items": {"type": "string", "enum": ["*","message.sent","message.delivered","message.failed"]}}
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {"type": "integer"},
          "limit": {"type": "integer"},
          "total": {"type": "integer"},
          "pages": {"type": "integer"},
          "has_more": {"type": "boolean"}
        }
      },
      "Envelope": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean", "example": true},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "MessageEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Message"}}}
        ]
      },
      "MessageListEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {
            "data": {"type": "array", "items": {"$ref": "#/components/schemas/Message"}},
            "pagination": {"$ref": "#/components/schemas/Pagination"}
          }}
        ]
      },
      "BulkResultEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {
            "data": {
              "type": "object",
              "properties": {
                "object": {"type": "string", "example": "bulk_result"},
                "total": {"type": "integer"},
                "sent": {"type": "integer"},
                "failed": {"type": "integer"},
                "messages": {"type": "array", "items": {"$ref": "#/components/schemas/Message"}}
              }
            }
          }}
        ]
      },
      "AccountEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {
            "type": "object",
            "properties": {
              "id": {"type": "string"},
              "object": {"type": "string", "example": "account"},
              "email": {"type": "string"},
              "name": {"type": "string"},
              "company_name": {"type": "string"},
              "country": {"type": "string"},
              "status": {"type": "string"},
              "kyc_verified": {"type": "boolean"},
              "balance": {"type": "number"},
              "currency": {"type": "string"},
              "created_at": {"type": "string", "format": "date-time"}
            }
          }}}
        ]
      },
      "BalanceEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {
            "type": "object",
            "properties": {
              "object": {"type": "string", "example": "balance"},
              "balance": {"type": "number"},
              "currency": {"type": "string"},
              "as_of": {"type": "string", "format": "date-time"}
            }
          }}}
        ]
      },
      "UsageEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {
            "type": "object",
            "properties": {
              "object": {"type": "string", "example": "usage"},
              "period": {"type": "string"},
              "starts_at": {"type": "string", "format": "date-time"},
              "ends_at": {"type": "string", "format": "date-time"},
              "currency": {"type": "string"},
              "totals": {
                "type": "object",
                "properties": {
                  "messages": {"type": "integer"},
                  "cost": {"type": "number"}
                }
              },
              "by_status": {
                "type": "object",
                "additionalProperties": {"type": "integer"}
              }
            }
          }}}
        ]
      },
      "SenderEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Sender"}}}
        ]
      },
      "SenderListEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {
            "data": {"type": "array", "items": {"$ref": "#/components/schemas/Sender"}},
            "pagination": {"$ref": "#/components/schemas/Pagination"}
          }}
        ]
      },
      "ApiKeyListEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {
            "type": "object",
            "properties": {
              "object": {"type": "string", "example": "list"},
              "data": {"type": "array", "items": {"$ref": "#/components/schemas/ApiKey"}}
            }
          }}}
        ]
      },
      "CreatedApiKeyEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {
            "allOf": [
              {"$ref": "#/components/schemas/ApiKey"},
              {"type": "object", "properties": {
                "plain_key": {"type": "string", "description": "Full plaintext key — shown only once."},
                "plain_key_notice": {"type": "string"}
              }}
            ]
          }}}
        ]
      },
      "DeletedEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {
            "type": "object",
            "properties": {
              "id": {"type": "string"},
              "object": {"type": "string"},
              "deleted": {"type": "boolean", "example": true}
            }
          }}}
        ]
      },
      "WebhookEndpointEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/WebhookEndpoint"}}}
        ]
      },
      "WebhookEndpointWithSecretEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {
            "allOf": [
              {"$ref": "#/components/schemas/WebhookEndpoint"},
              {"type": "object", "properties": {
                "signing_secret": {"type": "string", "description": "HMAC SHA-256 signing secret. Returned only on creation."}
              }}
            ]
          }}}
        ]
      },
      "WebhookEndpointListEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {"data": {
            "type": "object",
            "properties": {
              "object": {"type": "string", "example": "list"},
              "data": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookEndpoint"}}
            }
          }}}
        ]
      },
      "EventListEnvelope": {
        "allOf": [
          {"$ref": "#/components/schemas/Envelope"},
          {"type": "object", "properties": {
            "data": {"type": "array", "items": {"$ref": "#/components/schemas/Event"}},
            "pagination": {"$ref": "#/components/schemas/Pagination"}
          }}
        ]
      }
    }
  },
  "x-webhooks": {
    "message.sent": {
      "post": {
        "summary": "Sent to your endpoint when a message is accepted by an upstream provider.",
        "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}},
        "responses": {"200": {"description": "Return 2xx within 10s to acknowledge."}}
      }
    },
    "message.delivered": {
      "post": {
        "summary": "Sent when the carrier confirms delivery (via DLR).",
        "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}},
        "responses": {"200": {"description": "Return 2xx within 10s to acknowledge."}}
      }
    },
    "message.failed": {
      "post": {
        "summary": "Sent when delivery fails permanently.",
        "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Event"}}}},
        "responses": {"200": {"description": "Return 2xx within 10s to acknowledge."}}
      }
    }
  }
}