> For the complete documentation index, see [llms.txt](https://devcenter.unico.io/unico-people/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devcenter.unico.io/unico-people/unico-people-v1/apis/webhooks/create-webhook.md).

# Create webhook

Cria uma integração via webhook que é disparado para a api cadastrada quando determinados eventos relacionados a posição ocorrerem.

<mark style="color:orange;">`POST`</mark> \ <mark style="color:$primary;">**Url Produção:**</mark> `https://api.acessorh.com.br`\ <mark style="color:$primary;">**Url Homologação:**</mark> `https://api.rh.homolog.acesso.io`\ <mark style="color:$primary;">**Endpoint:**</mark> `/v1/integrations/webhook`

### **Headers**

| Key                                             | Type   | Description                                                    |
| ----------------------------------------------- | ------ | -------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Token de acesso adquirido pela plataforma Identity *(bearer)*. |

### Descrição do body JSON da request <a href="#descricao-do-body-json-da-request" id="descricao-do-body-json-da-request"></a>

#### **Obrigatórios**&#x20;

| Key                                           | Type   | Description                                                                                                              |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| **account**<mark style="color:red;">\*</mark> | string | UID da [empresa](https://devcenter.unico.io/unico-people/unico-people-v1/apis/organizacao.md#get-organization) desejada. |
| **data**<mark style="color:red;">\*</mark>    | object | Configuração do callback que será realizado.                                                                             |

**Data**

Neste ponto serão cadastrados o gatilho ou "trigger" do webhook (motivo pelo qual a chamada do webhook acontecerá), e a URL a qual receberá este aviso.

| Key                                          | Type                                                                                   | Description                                                                             |
| -------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **url**<mark style="color:red;">\*</mark>    | string                                                                                 | <p>URL para a execução do callback. Aceito apenas</p><p>endereços HTTPS.</p>            |
| **events**<mark style="color:red;">\*</mark> | array\[[string](https://acessorh.gitbook.io/project/api/webhooks#eventos-monitorados)] | <p>Lista de eventos que este webhook irá acompanhar</p><p>para executar o callback.</p> |

**Eventos monitorados**

{% hint style="success" %}
Os eventos que poderão ser acompanhados pelos webhooks são:

* **position-created** (uma posição foi criada na empresa/filial configurada);
* **position-applied** (um candidato aplicou em uma posição na empresa/filial configurada);
* **position-completed** (uma posição foi concluída pela análise do Acesso RH ou manualmente pelo DP da empresa/filial configurada);
* **position-archived** (uma posição foi arquivada pelo DP da empresa/filial configurada);
* **position-declined** (uma posição que foi declinada da vaga).
  {% endhint %}

#### **Opcionais**

| Key               | Type   | Description                                                                                                      |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| **unit**          | string | UID da [filial](https://devcenter.unico.io/unico-people/unico-people-v1/apis/organizacao.md#get-units) desejada. |
| **authorization** | object | Método de autenticação a ser realizado.                                                                          |

{% hint style="warning" %}
Caso o parâmetro `unit` não seja passado, o callback será executado para todas as filiais da empresa.
{% endhint %}

**Authorization**

Para proteger as requisições de callback do webhook, é possível selecionar três opções: **basic** , **secret** ou **apiKey**. Cada uma das opções requer configurações diferentes as quais você pode encontrar mais abaixo.

{% hint style="danger" %}
Em caso de athorization, é obrigatório informar o <mark style="color:$warning;">**kind**</mark> e o <mark style="color:$warning;">**data.**</mark>
{% endhint %}

| Key                                        | Type               | Description                                     |
| ------------------------------------------ | ------------------ | ----------------------------------------------- |
| **kind**<mark style="color:red;">\*</mark> | string (*options*) | Tipo da autenticação que será realizada.        |
| **data**<mark style="color:red;">\*</mark> | object             | Configuração do tipo de autenticação escolhido. |

**Opções de kind**

```json
basic, secret, apiKey
```

**Authorization: data (basic)**

{% hint style="info" %}
Na opção ***basic***, o callback será executado com um header **Authorization: basic \<credenciais>**. As credenciais serão o usuário e senha concatenados por dois pontos (**:**) e codificados em base64.
{% endhint %}

| Key                                            | Type   | Description       |
| ---------------------------------------------- | ------ | ----------------- |
| **username**<mark style="color:red;">\*</mark> | string | Nome do usuário.  |
| **password**<mark style="color:red;">\*</mark> | string | Senha do usuário. |

**Authorization: data (secret)**

{% hint style="info" %}
Na opção ***secret***, a intenção é que o recebedor consiga se certificar de que o callback recebido foi realizado pelo Acesso RH. Por isso, o callback será executado com um header **Acesso-Signature: \<assinatura>**, sendo a assinatura um hash criado para cada payload. O Acesso RH utiliza um **HMAC** em conjunto com uma chave **sha256** e o **secret** configurado para calcular e gerar esta assinatura, codificando-a em base64. O mesmo procedimento deve ser realizado na aplicação que receberá esta requisição, comparando a chave gerada e a presente no header. [**Aqui** ](https://acessorh.gitbook.io/project/api/webhooks#calcular-assinatura-do-payload)alguns exemplos de como criar esta verificação.
{% endhint %}

| Key                                          | Type   | Description                      |
| -------------------------------------------- | ------ | -------------------------------- |
| **secret**<mark style="color:red;">\*</mark> | string | Chave que assinará a requisição. |

**ApiKey: data (apiKey)**

{% hint style="info" %}
Na opção **apiKey**, o callback será executado com um header **Authorization: \<prefix> \<key>**. Onde o prefix é um campo opcional e key a chave da apiKey. Prefix e key são separados por um espaço em branco.
{% endhint %}

| Key                                   | Type   | Description                                             |
| ------------------------------------- | ------ | ------------------------------------------------------- |
| key<mark style="color:red;">\*</mark> | string | Chave da apiKey                                         |
| prefix                                | string | Prefixo opcional que pode acompanhar o valor da apiKey. |

### Exemplos de requisição

{% tabs %}
{% tab title="Apenas obrigatorios" %}

```json
{
  	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
  	"data": {
  		"url": "https://api.teste.com.br/callback",
  		"events": [
  			"position-created",
  			"position-archived",
  			"position-completed"
  		]
  	}
}
```

{% endtab %}

{% tab title="secret" %}

```json
{
  	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
  	"unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
  	"authorization": {
  		"kind": "secret",
  		"data": {
  			"secret": "tme0dQq1CIDm4PYsfK!d"
  		}
  	},
  	"data": {
  		"url": "https://api.teste.com.br/callback",
  		"events": [
  			"position-created",
  			"position-archived",
  			"position-completed"
  		]
  	}
}
```

{% endtab %}

{% tab title="basic" %}

```json
{
	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
        "unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
	"authorization": {
		"kind": "basic",
		"data": {
                       "username": "teste",
		       "password": "1234"
		}
	},
	"data": {
		"url": "https://api.teste.com.br/callback",
		"events": [
			"position-created",
			"position-archived"
		]
	}
}
```

{% endtab %}

{% tab title="apiKey" %}

```json
{
	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
        "unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
	"authorization": {
		"kind": "apiKey",
		"data": {
                       "key": "password123",
		       "prefix": "X-Api-Key" // opcional
		}
	},
	"data": {
		"url": "https://api.teste.com.br/callback",
		"events": [
			"position-created",
			"position-archived"
		]
	}
}
```

{% endtab %}

{% tab title="Put webhook" %}

```json
{
	"id": "b712a527-efec-4e02-83d5-95cbd7c269f9",
	"account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
        "unit": "82930d53-e99a-4927-b31e-4fdc7090395d",
	"authorization": {
		"kind": "apiKey",
		"data": {
                       "key": "password123",
		       "prefix": "X-Api-Key"
		}
	},
	"data": {
		"url": "https://api.teste.com.br/callback",
		"events": [
			"position-created",
			"position-archived"
		]
	}
}
```

{% endtab %}
{% endtabs %}

### Exemplo de response

{% code title="201 OK" %}

```json
{
    "account": "2d9174c4-06b7-4956-a5dc-8824d8a2f49e",
    "authorization": {
        "kind": "secret"
    },
    "data": {
        "url": "https://api.teste.com.br/callback",
        "events": [
            "position-created",
            "position-archived",
            "position-completed"
        ]
    },
    "uid": "a7c001fe-50bb-41cd-a910-da27e538726f",
    "unit": "82930d53-e99a-4927-b31e-4fdc7090395d"
}
```

{% endcode %}

### Exemplo de callback <a href="#exemplo-de-callback" id="exemplo-de-callback"></a>

**Headers**

| Header                 | Description                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Acesso-Delivery-Id** | UID do callback                                                                                                                                                                                                                                                                                                                                        |
| **Acesso-Signature**   | <p>Caso a opção <strong>Secret</strong> tenha sido selecionada em</p><p><strong>Authorization</strong>, armazena a assinatura do body da requisição</p>                                                                                                                                                                                                |
| **Authorization**      | <p>Caso a opção <strong>Basic</strong> ou <strong>ApiKey</strong> tenha sido selecionada em <strong>Authorization.</strong> Para <strong>Basic</strong> esse header armazena o usuário e senha concatenados e</p><p>codificados em base64, enquanto para <strong>ApiKey</strong> será a própria key pura com o prefixo caso tenha sido cadastrado.</p> |
| **Content-Type**       | Identifica o tipo do body da requisição                                                                                                                                                                                                                                                                                                                |

**Body**

```json
{
    "integration": "0a22e148-6610-4d38-bcb7-20bbc465d43c",
    "position": "302fc619-2054-448c-a9f8-d1093fcaddf2",
    "position-number": "ABC123",
    "unit": "8a240932-7c99-40da-aeb8-37a89308c642",
    "event": "position-archived"
}
```

### Calcular assinatura do payload <a href="#calcular-assinatura-do-payload" id="calcular-assinatura-do-payload"></a>

Abaixo, seguem alguns exemplos de códigos para calcular a assinatura do payload quando a opção secret for configurada nos webhooks:

* **C#**
* **Go**
* **Java**
* **Python 3**

{% code title="C#" %}

```csharp
using System.Security.Cryptography;

private static byte[] HashHMAC(byte[] msg, String secret)
{
    var key = Encoding.ASCII.GetBytes(secret);
    var hash = new HMACSHA256(key);
    return Convert.ToBase64String(hash.ComputeHash(msg));
}
```

{% endcode %}

{% code title="Go" %}

```go
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
)

func HashHMAC(msg []byte, secret string) string {
	key := []byte(secret)	
	h := hmac.New(sha256.New, key)
	h.Write(msg)
	return base64.StdEncoding.EncodeToString(h.Sum(nil))
}
```

{% endcode %}

{% code title="Java" %}

```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public static byte[] HashHMAC(byte[] msg, String secret) {
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
    sha256_HMAC.init(secret_key);
    
    String hash = Base64.encodeBase64String(sha256_HMAC.doFinal(msg));
}
```

{% endcode %}

{% code title="Python" %}

```python
import hashlib
import hmac
import base64

def hashHMAC(msg, secret):
    key = bytes(secret, 'utf-8')

    signature = base64.b64encode(hmac.new(key, message, digestmod=hashlib.sha256).digest())
    return signature
```

{% endcode %}
