Receive a provider webhook on a tenant connection

curl --request POST \
  --url https://payments.sandbox.lerian.net/v1/webhooks/btg/{connection_token} \
  --header 'Content-Type: application/json' \
  --header 'x-webhook-baas-signature: <x-webhook-baas-signature>' \
  --data '
{
  "entity": "<string>",
  "pactualId": "<string>",
  "status": "<string>",
  "clientRequestId": "<string>",
  "createTimestamp": "2023-11-07T05:31:56Z"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://payments.sandbox.lerian.net/v1/webhooks/btg/{connection_token}"

	payload := strings.NewReader("{\n  \"entity\": \"<string>\",\n  \"pactualId\": \"<string>\",\n  \"status\": \"<string>\",\n  \"clientRequestId\": \"<string>\",\n  \"createTimestamp\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-webhook-baas-signature", "<x-webhook-baas-signature>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'x-webhook-baas-signature': '<x-webhook-baas-signature>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entity: '<string>',
    pactualId: '<string>',
    status: '<string>',
    clientRequestId: '<string>',
    createTimestamp: '2023-11-07T05:31:56Z'
  })
};

fetch('https://payments.sandbox.lerian.net/v1/webhooks/btg/{connection_token}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://payments.sandbox.lerian.net/v1/webhooks/btg/{connection_token}"

payload = {
    "entity": "<string>",
    "pactualId": "<string>",
    "status": "<string>",
    "clientRequestId": "<string>",
    "createTimestamp": "2023-11-07T05:31:56Z"
}
headers = {
    "x-webhook-baas-signature": "<x-webhook-baas-signature>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Receive a provider webhook on a tenant connection

Accepts a settlement event pushed by the payment provider on a per-tenant webhook connection, persists it verbatim and returns 202 only after that persistence succeeds. This route is served only by a multi-tenant deployment; a single-tenant deployment serves the unparameterised provider webhook route instead, and this document advertises both because it is generated without a deployment mode. The connection_token path segment names a webhook connection this service issued when a tenant connected the provider: it selects the tenant the delivery belongs to, the storage it is written to, and the key its signature is verified under. Authentication is an HMAC-SHA256 signature over the raw request body, sent as lowercase hex in x-webhook-baas-signature and computed with the secret agreed for that one connection, not a platform identity and not a key shared between tenants. A connection_token that names no connection, a connection that has been revoked, and a signature that does not match the body are refused with the same 401 and cannot be told apart. If the tenant’s storage is unavailable the event is not persisted and the response is 503 (retryable) instead of 202. The body is the provider envelope: pactualId, entity and status are required, clientRequestId and createTimestamp are optional, and any further member is accepted and stored as sent. Member names are matched without regard to case. The x-webhook-baas-entity and x-webhook-baas-event headers are optional copies of entity and status; where a header disagrees with the body the body is authoritative, because only the body is signed. The x-webhook-baas-notifyid header identifies the logical notification and, when sent, is what this endpoint deduplicates on; a delivery without it is still accepted and deduplicated on a key derived from pactualId, entity, status and createTimestamp. The x-webhook-baas-deliveryid header names one attempt to deliver that notification rather than the notification itself; it is optional, it decides nothing, and it is recorded only in this endpoint’s logs, so that a delivery can be matched against the provider’s own list of failed attempts. A delivery whose status names a provider TRANSPORT event rather than a business one — PING, which the provider’s own webhook test emits and which belongs to no entity’s event catalogue — is the single exception to all of the above: it is answered 202 without being deduplicated and without being persisted.

POST

webhooks

btg

{connection_token}

Receive a provider webhook on a tenant connection

curl --request POST \
  --url https://payments.sandbox.lerian.net/v1/webhooks/btg/{connection_token} \
  --header 'Content-Type: application/json' \
  --header 'x-webhook-baas-signature: <x-webhook-baas-signature>' \
  --data '
{
  "entity": "<string>",
  "pactualId": "<string>",
  "status": "<string>",
  "clientRequestId": "<string>",
  "createTimestamp": "2023-11-07T05:31:56Z"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://payments.sandbox.lerian.net/v1/webhooks/btg/{connection_token}"

	payload := strings.NewReader("{\n  \"entity\": \"<string>\",\n  \"pactualId\": \"<string>\",\n  \"status\": \"<string>\",\n  \"clientRequestId\": \"<string>\",\n  \"createTimestamp\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-webhook-baas-signature", "<x-webhook-baas-signature>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'x-webhook-baas-signature': '<x-webhook-baas-signature>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entity: '<string>',
    pactualId: '<string>',
    status: '<string>',
    clientRequestId: '<string>',
    createTimestamp: '2023-11-07T05:31:56Z'
  })
};

fetch('https://payments.sandbox.lerian.net/v1/webhooks/btg/{connection_token}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://payments.sandbox.lerian.net/v1/webhooks/btg/{connection_token}"

payload = {
    "entity": "<string>",
    "pactualId": "<string>",
    "status": "<string>",
    "clientRequestId": "<string>",
    "createTimestamp": "2023-11-07T05:31:56Z"
}
headers = {
    "x-webhook-baas-signature": "<x-webhook-baas-signature>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Cabeçalhos

x-webhook-baas-signature

string

obrigatório

HMAC-SHA256 of the raw request body, lowercase hex. WHICH key signs it depends on the route: the unparameterised route verifies against the deployment-wide provider secret, while the per-connection route verifies against the signing key issued for that connection_token and nothing else — a delivery signed with the deployment-wide secret is refused there. It is verified by a per-operation middleware that runs before any schema check, so a request that omits it, or carries a value that does not match the body, is refused with 401 PBP-0500 and never with a schema error.

x-webhook-baas-entity

string

Provider entity name, repeating the body's entity member. Cross-checked against it; the body decides, because only the body is under the signature.

x-webhook-baas-event

string

Provider event name, which is the same value as the body's status member. Cross-checked against it; the body decides.

x-webhook-baas-notifyid

string

Provider identifier of the LOGICAL notification, as opposed to one delivery attempt of it. When present it becomes this delivery's deduplication key; when absent the key is derived from the envelope instead, and the delivery is still accepted.

x-webhook-baas-deliveryid

string

Provider identifier of ONE ATTEMPT to deliver a notification, as opposed to the notification itself. It decides nothing: it is never deduplicated on and no column holds it, because an attempt identifier is fresh on every retry. It is recorded in this endpoint's logs so a delivery can be matched against the provider's own list of failed attempts. A delivery without it is still accepted.

X-Correlation-Id

string

Optional provider correlation identifier. Persisted with the event when present.

Parâmetros de caminho

connection_token

string

obrigatório

Opaque token identifying the webhook connection this service issued for one tenant and one provider. It selects the tenant the delivery belongs to, the storage it is written to, and the secret its body signature is verified under. A token that names no connection and a token whose connection has been revoked are refused identically, and neither is echoed back.

Corpo

application/json

entity

string

obrigatório

Provider entity name the event belongs to, for example PaymentSlipPay or TaxDarfPayment. Cross-checked against x-webhook-baas-entity; the body wins.

pactualId

string

obrigatório

Provider-assigned primary key of the entity this event is about. A string representation of a GUID in every delivery seen so far, but not validated as one: the field is the provider's to shape.

status

string

obrigatório

Provider state the entity moved to, for example PAID. This IS the provider's event name — the x-webhook-baas-event header carries the same value — and it is stored as sent.

clientRequestId

string

Identifier this service sent when it created the entity, echoed back for correlation. Optional here even though the provider envelope declares it required.

createTimestamp

string<date-time>

Instant the provider recorded for this state, RFC 3339. Optional here: a delivery without one means no reference instant, not a malformed request.

Resposta

Accepted

API de Boletos

API de Pagamentos

API de Dashboards

API de Administração

API de Webhooks

Tratamento de erros

Receive a provider webhook on a tenant connection

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta