Webhooks

This section gathers endpoints for managing notifications by the receiving PSP for the end user recipient.

Configure Webhook

Endpoint to create a new webhook configuration to receive automatic notifications of DICT events.

POST /v1/webhook

Requires authorization for the scope: webhook.write

Request

Example

{
  "webhookUrl": "https://api.exemplo.com/webhook/dict",
  "contexts": [
    "dict-claim",
    "dict-refund-request"
  ]
}

Responses

The responses below represent Success(201) from the consumption.

🟢 201

{
  "uuid": "dd320762-cbf1-465a-b7d8-2fddf51325ac"
}

🔴 401

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "invalid or inactive credentials",
    "status": 401,
    "title": "invalid_client"
  }
}

🔴 403

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Participant is not allowed to access this resource",
    "status": 403,
    "title": "Forbidden"
  }
}

🔴 500

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Our service is currently experiencing an issue. We apologize for the inconvenience and are working to resolve it as soon as possible.",
    "status": 500,
    "title": "Internal Server Error"
  }
}

🔴 503

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Service is under scheduled maintenance",
    "status": 503,
    "title": "Service Unavailable",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/ServiceUnavailable"
  }
}

List Webhooks

Endpoint to list all webhooks configured for your account.

GET /v1/webhook

Requires authorization for the scope: webhook.read

Request

The request sent to this endpoint does not require a body, only the OAuth authorization headers and the account certificate.

Responses

The response below represents a Success(200) consumption.

🟢 200

{
  "webhooks": [
    {
      "id": "dd320762-cbf1-465a-b7d8-2fddf51325ac",
      "webhookUrl": "https://api.exemplo.com/webhook/dict",
      "cnpj": "12345678000195",
      "criacao": "2024-01-15T10:30:00Z",
      "contexts": [
        "dict-claim",
        "dict-refund-request"
      ]
    }
  ]
}

Get Webhook

Endpoint to retrieve specific details of a webhook.

GET /v1/webhook/:uuid

Requires authorization for the scope: webhook.read

Responses

The responses below represent Success(200) and Failures/errors from the request.

🟢 200

{
  "id": "dd320762-cbf1-465a-b7d8-2fddf51325ac",
  "webhookUrl": "https://api.exemplo.com/webhook/dict",
  "contexts": [
    "dict-claim",
    "dict-refund-request"
  ],
  "criacao": "2024-01-15T10:30:00Z"
}

🔴 401

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "invalid or inactive credentials",
    "status": 401,
    "title": "invalid_client"
  }
}

🔴 403

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Participant is not allowed to access this resource",
    "status": 403,
    "title": "Forbidden"
  }
}

🔴 500

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Our service is currently experiencing an issue. We apologize for the inconvenience and are working to resolve it as soon as possible.",
    "status": 500,
    "title": "Internal Server Error"
  }
}

🔴 503

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Service is under scheduled maintenance",
    "status": 503,
    "title": "Service Unavailable",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/ServiceUnavailable"
  }
}

Update Webhook Contexts

Endpoint to update the contexts of an existing webhook.

PUT /v1/webhook/:uuid

Requires authorization for the scope: webhook.write

Request

Example

{
  "contexts": [
    "dict-claim",
    "dict-refund-request"
  ]
}

Responses

The responses below represent Success(200) from the consumption.

🟢 200

{
  "id": "dd320762-cbf1-465a-b7d8-2fddf51325ac",
  "webhookUrl": "https://api.exemplo.com/webhook/dict",
  "criacao": "2024-01-15T10:30:00Z",
  "contexts": [
    "dict-claim",
    "dict-refund-request"
  ]
}

🔴 401

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "invalid or inactive credentials",
    "status": 401,
    "title": "invalid_client"
  }
}

🔴 403

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Participant is not allowed to access this resource",
    "status": 403,
    "title": "Forbidden"
  }
}

🔴 500

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Our service is currently experiencing an issue. We apologize for the inconvenience and are working to resolve it as soon as possible.",
    "status": 500,
    "title": "Internal Server Error"
  }
}

🔴 503

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Service is under scheduled maintenance",
    "status": 503,
    "title": "Service Unavailable",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/ServiceUnavailable"
  }
}

Delete Webhook

Endpoint to permanently remove a configured webhook.

DELETE /v1/webhook/:uuid

Requires authorization for the scope: webhook.write

Responses

The responses below represent Success(200) and Failure/error consumption.

🟢 200

{
  "id": "dd320762-cbf1-465a-b7d8-2fddf51325ac",
  "webhookUrl": "https://api.exemplo.com/webhook/dict",
  "criacao": "2024-01-15T10:30:00Z",
  "contexts": [
    "dict-claim",
    "dict-refund-request"
  ]
}

🔴 401

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "invalid or inactive credentials",
    "status": 401,
    "title": "invalid_client"
  }
}

🔴 403

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Participant is not allowed to access this resource",
    "status": 403,
    "title": "Forbidden"
  }
}

🔴 500

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Our service is currently experiencing an issue. We apologize for the inconvenience and are working to resolve it as soon as possible.",
    "status": 500,
    "title": "Internal Server Error"
  }
}

🔴 503

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Service is under scheduled maintenance",
    "status": 503,
    "title": "Service Unavailable",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/ServiceUnavailable"
  }
}