urlstring · uriRequired← HomeFleetPay / API
Register new outbound webhook subscription
Parameters, data structure and responses from the versioned contract.
POST
/webhooks/assinaturasTechnical descriptions are translated from the versioned contract. Original identifiers and JSON are preserved; data examples are omitted.
Registers a public HTTPS URL, subscribed events and returns signing_secret once on creation. Rejects private/local URLs or HTTP in production (anti-SSRF). Requires operacao scope.
Authentication
- Required Scope
operacao— Operations- Module
- Webhooks & Subscriptions
- Target Profiles
- Shipper · Transport Manager · Dedicated Fleet Contractor · Fleet Carrier
- Schemes
- OAuth2 client_credentials (POST /oauth/token) or API Key via Authorization: Bearer / X-Api-Key
[
{
"oauth2": []
},
{
"chaveApi": []
}
]Availability depends on the environment, enabled scopes and provider. This reference does not execute requests or collect credentials.
Parameters
No parameters declared for this operation.
Request Body
Required
Destination URL and subscribed events.
application/json
eventsarrayRequireddescriptionstring | nullOptionalResponses
201 HTTP Response
Webhook subscription created with initial secret.
application/json
data—Optionalmetaobject | nullOptionaladditionalPropertiestrueambientestringOptional"homologacao" · "producao"401 HTTP Response
Missing, invalid or cross-environment credential.
403 HTTP Response
Dashboard scope not enabled or resource outside company scope.
422 HTTP Response
Invalid/unsafe URL or unknown event.
Complete Operation Definition
{
"tags": [
"Webhooks"
],
"operationId": "criarAssinaturaWebhook",
"summary": "Cadastrar nova assinatura webhook outbound",
"description": "Registra URL HTTPS pública, eventos assinados e devolve `signing_secret` uma única vez na criação. Rechaza URLs privadas/locais ou HTTP em produção (anti-SSRF). Exige escopo `operacao`.",
"requestBody": {
"required": true,
"description": "URL de destino e eventos assinados.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url",
"events"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"responses": {
"201": {
"description": "Assinatura webhook criada com segredo inicial.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
]
},
"meta": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"ambiente": {
"type": "string",
"enum": [
"homologacao",
"producao"
]
}
}
}
}
}
},
"401": {
"description": "Credencial ausente, inválida ou de outro ambiente."
},
"403": {
"description": "Escopo do painel não habilitado ou recurso fora do escopo da company."
},
"422": {
"description": "URL inválida/insegura ou evento desconhecido."
}
},
"x-fleetpay-scope": "operacao",
"x-fleetpay-module": "webhooks",
"x-fleetpay-profiles": [
"embarcador",
"gestor",
"agregado_empresarial",
"transportador_frotista"
],
"method": "POST",
"path": "/webhooks/assinaturas",
"parameters": []
}