Webhooks (`Webhook`)

O Financeiro possui um sistema de notificação via webhooks. Ele possibilita que você receba notificações em um endpoint especificado por você (uma URL do seu sistema).

Este endpoint precisa estar ativo e respondendo para o webhook com HTTP 200 Ok. O Financeiro fará no máximo 5 tentativas de notificação. Após a 5ª tentativa sem sucesso, o administrador da conta será notificado via e-mail e o endpoint deste webhook será marcado como "Com erro".

Lista de eventos:

Contas a pagar

Contas a receber

Contas bancárias

deposit_accounts.created
deposit_accounts.updated
deposit_accounts.destroyed
deposit_accounts.archived
deposit_accounts.unarchived

Lançamentos

financial_transactions.created
financial_transactions.updated
financial_transactions.destroyed
financial_transactions.reconciled

Extratos

bank_statements.created
bank_statements.imported
bank_statements.import_failed

Cartões de crédito

credit_cards.created
credit_cards.updated
credit_cards.destroyed
credit_cards.archived
credit_cards.unarchived

Lançamentos de Cartões de crédito

credit_card_transactions.created
credit_card_transactions.updated
credit_card_transactions.destroyed
credit_card_transactions.moved

Categorias

categories.created
categories.updated
categories.destroyed

Clientes / Fornecedores

people.created
people.updated
people.destroyed

Centro de custos / receitas

classification_centers.created
classification_centers.updated
classification_centers.destroyed

Anexos

attachments.created
attachments.updated
attachments.destroyed

Recebível

sales.created
sales.updated
sales.destroyed
sales.financial_transaction_associated
sales.financial_transaction_disassociated

Conta de Recebível

sale_accounts.created
sale_accounts.updated
sale_accounts.destroyed

Regra de Recebível

sale_rules.created
sale_rules.updated
sale_rules.destroyed

Permissão

Somente o administrador da conta pode usar os endpoints a seguir. Qualquer token que não seja do Administrador receberá um erro 403 Forbidden.

Headers de segurança:

Quando um evento é notificado, são utilizados 2 headers de segurança que permitem garantir a autenticidade de quem enviou a requisição e o conteúdo da mensagem.

O header X-Myfinance-RequestId é um identificador único e randômico da requisição. Com este identificador podemos garantir que um atacante não irá efetuar um replay attack, uma vez que esse identificador não poderá se repetir.

O header X-Myfinance-Signature é a assinatura da requisição composta por:

O segredo informado quando do cadastro da integração;
O identificador único da requisição (X-Myfinance-RequestId);
O corpo da requisição.

A assinatura é formada concatenando-se o conteúdo de X-Myfinance-RequestId + o corpo da requisição. Ao resultado disso deve ser aplicado um HMAC digest SHA1, conforme examplo abaixo:

SHA1(X-Myfinance-RequestId + request_body)

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 30 Sep 2015 17:40:36 GMT
X-Myfinance-RequestId: d12c56319826262a371989930be7d0b2
X-Myfinance-Signature: b09209a810d67b382193680a0342896c2cb042a8

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <event>classification_centers.destroyed</event>
  <timestamp>2015-09-30T18:01:42Z</timestamp>
  <classification-center>
    <id type="integer">10</id>
    <_links>
      <rel>self</rel>
      <method>GET</method>
      <url>https://financeiro.fintera.com.br/classification_centers/10</url>
    </_links>
  </classification-center>
</hash>

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 30 Sep 2015 17:40:36 GMT
X-Myfinance-RequestId: d12c56319826262a371989930be7d0b2
X-Myfinance-Signature: b09209a810d67b382193680a0342896c2cb042a8

{
  "event": "classification_centers.destroyed",
  "timestamp": "2015-09-30T17:40:36Z",
  "classification_center": {
    "id": 10,
    "_links": {
      "rel": "self",
      "method": "GET",
      "url": "https://financeiro.fintera.com.br/classification_centers/10"
    }
  }
}

Listar webhooks

GET /integrations/webhooks

Retorna uma lista de todas os webhooks da Account.

Exemplo de Resposta

JSON
XML

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT

<?xml version="1.0" encoding="UTF-8"?>
<webhooks type="array">
  <webhook>
    <account-id type="integer">2</account-id>
    <created-at type="dateTime">2015-09-21T15:41:05-03:00</created-at>
    <description>Webhook edit 2</description>
    <entity-id type="integer">3</entity-id>
    <healthy-check-code>200</healthy-check-code>
    <id type="integer">22</id>
    <updated-at type="dateTime">2015-09-21T16:08:48-03:00</updated-at>
    <url>http://requestb.in/yl4vfwyl</url>
  </webhook>
  <webhook>
    <account-id type="integer">2</account-id>
    <created-at type="dateTime">2015-09-21T16:15:22-03:00</created-at>
    <description>Webhook edit 1</description>
    <entity-id type="integer">3</entity-id>
    <healthy-check-code>200</healthy-check-code>
    <id type="integer">23</id>
    <updated-at type="dateTime">2015-09-21T16:15:35-03:00</updated-at>
    <url>http://requestb.in/o31a9qo3</url>
  </webhook>
</webhooks>

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT

[
  {
    "webhook":
      {
        "account_id":2,
        "created_at":"2015-09-21T15:41:05-03:00",
        "description":"Webhook edit 2",
        "entity_id":3,
        "healthy_check_code":"200",
        "id":22,
        "updated_at":"2015-09-21T16:08:48-03:00",
        "url":"http://requestb.in/yl4vfwyl"
      }
  },
  {
    "webhook":
      {
        "account_id":2,
        "created_at":"2015-09-21T16:15:22-03:00",
        "description":"Webhook edit 1",
        "entity_id":3,
        "healthy_check_code":"200",
        "id":23,
        "updated_at":"2015-09-21T16:15:35-03:00",
        "url":"http://requestb.in/o31a9qo3"
      }
  }
]

Exibir um webhook

GET /integrations/webhooks/:id

Retorna os atributos do webhook especificado com uma resposta 200 Ok.

Exemplo de Resposta

JSON
XML

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT

<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <account-id type="integer">2</account-id>
  <created-at type="dateTime">2015-09-21T15:41:05-03:00</created-at>
  <description>Webhook edit 2</description>
  <entity-id type="integer">3</entity-id>
  <healthy-check-code>200</healthy-check-code>
  <id type="integer">22</id>
  <updated-at type="dateTime">2015-09-21T16:08:48-03:00</updated-at>
  <url>http://requestb.in/yl4vfwyl</url>
</webhook>

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT

{
  "webhook":
    {
      "account_id":2,
      "created_at":"2015-09-21T15:41:05-03:00",
      "description":"Webhook edit 2",
      "entity_id":3,
      "healthy_check_code":"200",
      "id":22,
      "updated_at":"2015-09-21T16:08:48-03:00",
      "url":"http://requestb.in/yl4vfwyl"
    }
}

Criar um webhook

POST /integrations/webhooks

Cria um novo webhook com os parâmetros informados. Em caso de sucesso, retorna 201 Created, juntamente com a URI do webhook criado no cabeçalho Location da resposta HTTP. Em caso de falha, retorna 422 Unprocessable entity juntamente com a descrição dos erros.

Você pode configurar o webhook de forma que o corpo da requisição seja um json ou um xml, basta informar o campo format ao cadastrar um webhook.

Exemplo de Requisição

JSON
XML

{
  "webhook": {
    "entity_id": 3,
    "description": "Webhook test",
    "url": "http://requestb.in/xssmudxs"
    "format": "json"
  }
}

<webhook>
  <entity-id>3</entity-id>
  <description>Webhook test</description>
  <url>http://requestb.in/xssmudxs<url>
  <format>xml</format>
</webhook>

Exemplo de Resposta

JSON
XML

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/integrations/webhooks/24
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT

{
  "webhook":
    {
      "account_id":2,
      "created_at":"2015-09-23T11:27:14-03:00",
      "description":null,
      "entity_id":3,
      "healthy_check_code":200,
      "id":24,
      "updated_at":"2015-09-23T11:27:14-03:00",
      "url":"http://requestb.in/xssmudxs"
      "format":"json"
    }
}

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/integrations/webhooks/24
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT

<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <account-id type="integer">2</account-id>
  <created-at type="dateTime">2015-09-23T11:40:06-03:00</created-at>
  <description nil="true"/>
  <entity-id type="integer">3</entity-id>
  <healthy-check-code type="integer">200</healthy-check-code>
  <id type="integer">24</id>
  <updated-at type="dateTime">2015-09-23T11:40:06-03:00</updated-at>
  <url>http://requestb.in/xssmudxs</url>
  <format>xml</format>
</webhook>

Requisição de teste

Ao cadastrar um novo webhook, o Financeiro fará uma requisição do tipo POST de teste para garantir o funcionamento do endpoint informado. Esta requisição deve retornar 200 Ok, caso contrário, não será possível cadastrar webhook e a API retornará o seguinte erro: A URL não respondeu à requisição de teste.

Exemplo da requisição de teste enviada pelo Financeiro

JSON
XML

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/integrations/webhooks/24
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT

{
  "test": true
}

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/integrations/webhooks/24
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <test type="boolean">true</test>
</hash>

Alterar um webhook

PUT /integrations/webhooks/:id

Altera os dados do webhook especificado. Só pode alterar o campo description. Retorna uma resposta vazia com status 200 OK.

Em caso de erro, retorna os erros que impediram de alterar o webhook.

Exemplo de Requisição

JSON
XML

{
  "webhook":
    {
      "account_id":2,
      "created_at":"2015-09-23T11:27:14-03:00",
      "description":"Descrição",
      "entity_id":3,
      "healthy_check_code":200,
      "id":24,
      "updated_at":"2015-09-23T11:27:14-03:00",
      "url":"http://requestb.in/xssmudxs"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <account-id type="integer">2</account-id>
  <created-at type="dateTime">2015-09-23T11:40:06-03:00</created-at>
  <description>Descrição</description>
  <entity-id type="integer">3</entity-id>
  <healthy-check-code type="integer">200</healthy-check-code>
  <id type="integer">24</id>
  <updated-at type="dateTime">2015-09-23T11:40:06-03:00</updated-at>
  <url>http://requestb.in/xssmudxs</url>
</webhook>

Valida o estado do webhook

PUT /integrations/webhooks/:id/verify_status

Retorna os dados do webhook depois de verififcado. Se necessário marcar como ativo, o retorno é com 200 OK.

Em caso de erro, retorna os erros que impediram de alterar o webhook.

Exemplo de Requisição

JSON
XML

{
  "webhook":
    {
      "account_id":2,
      "created_at":"2015-09-23T11:27:14-03:00",
      "description":"Descrição",
      "entity_id":3,
      "healthy_check_code":200,
      "id":24,
      "updated_at":"2015-09-23T11:27:14-03:00",
      "url":"http://requestb.in/xssmudxs"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <account-id type="integer">2</account-id>
  <created-at type="dateTime">2015-09-23T11:40:06-03:00</created-at>
  <description>Descrição</description>
  <entity-id type="integer">3</entity-id>
  <healthy-check-code type="integer">200</healthy-check-code>
  <id type="integer">24</id>
  <updated-at type="dateTime">2015-09-23T11:40:06-03:00</updated-at>
  <url>http://requestb.in/xssmudxs</url>
</webhook>

Apagar um webhook

Exemplo de Requisição

DELETE /integrations/webhooks/:id

Apaga o webhook especificado. Retorna uma resposta vazia com status 200 OK.

Webhooks (Webhook)

Lista de eventos:

Permissão

Headers de segurança:

Exemplo de Requisição

Listar webhooks

Exemplo de Resposta

Exibir um webhook

Exemplo de Resposta

Criar um webhook

Exemplo de Requisição

Exemplo de Resposta

Requisição de teste

Exemplo da requisição de teste enviada pelo Financeiro

Alterar um webhook

Exemplo de Requisição

Valida o estado do webhook

Exemplo de Requisição

Apagar um webhook

Exemplo de Requisição

Webhooks (`Webhook`)