← HomeFleetPay / API

Register new outbound webhook subscription

Parameters, data structure and responses from the versioned contract.

POST/webhooks/assinaturas
criarAssinaturaWebhookSandbox Base: https://api.fleetpay.site/v1

Technical 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

urlstring · uriRequired
eventsarrayRequired
descriptionstring | nullOptional

Responses

201 HTTP Response

Webhook subscription created with initial secret.

application/json

data—Optional
metaobject | nullOptional
additionalPropertiestrue
ambientestringOptional
"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": []
}