# Webhooks na ficha

> A única saída da ficha para a internet: declarar webhooks no manifesto e mandar dados para o Zapier, o Make ou o IFTTT.

Página: https://docs.rpgdesk.com/fichas/webhooks/

A ficha não acessa a internet. A única saída são os **webhooks**: a ficha manda dados com um nome (“rolagens”), e o mestre da mesa decide para onde eles vão, colando o endereço de um webhook do **Zapier**, do **Make** ou do **IFTTT**. Assim a ficha nunca escolhe o destino, e o endereço não aparece para os jogadores.

## Declarar

No manifesto:

```json
"webhooks": [
  { "name": "rolagens", "description": "Cada rolagem da ficha", "example": { "total": 17, "rolagem":
"1d20+5" } } ]
```

- `name`: minúsculas, números, `-` e `_`. A ficha usa esse nome para mandar.
- `description`: o que o webhook manda, para o mestre saber o que está ligando.
- `example` (opcional): um exemplo dos dados, até 4 KB.
- Até 20 webhooks por plugin.

Ao instalar, o RPG Desk mostra os webhooks ao mestre, que liga os endereços em **Configurações da mesa → Plugins → Integrações**. Veja [Integrações](https://docs.rpgdesk.com/mestres/integracoes/).

## Mandar

```js
const r = await RPGDesk.webhooks.send('rolagens', { total: 17, rolagem: '1d20+5' });
if (!r.ok) RPGDesk.ui.toast(`O webhook não foi: ${r.error}`, 'error');
```

O resultado é `{ ok, status, body, error }`:

| `error`            | Quando                                                    |
| ------------------ | --------------------------------------------------------- |
| `null`             | deu certo; `body` é a resposta do serviço                 |
| `'not-found'`      | o manifesto não declara um webhook com esse nome          |
| `'not-configured'` | o mestre ainda não ligou um endereço para esse webhook    |
| `'forbidden'`      | o webhook é **Só mestres**, e quem disparou é jogador     |
| `'bad-request'`    | os dados passam de 16 KB                                  |
| `'rate-limited'`   | envios demais em pouco tempo na mesa                      |
| `'timeout'`        | o serviço não respondeu em 10 segundos                    |
| `'failed'`         | o serviço respondeu com erro, ou não deu para chegar nele |

O RPG Desk manda os seus dados em `data`, junto com o plugin, o webhook, a mesa, quem disparou e a hora. O formato está em [Integrações](https://docs.rpgdesk.com/mestres/integracoes/#o-que-chega-no-servi%C3%A7o).

## Exemplo: cada rolagem no Discord

```html
<button id="atacar">Atacar</button>
<script>
  document.getElementById('atacar').addEventListener('click', async () => {
    const r = await RPGDesk.dice.roll('1d20+5', { label: 'Ataque' });
    await RPGDesk.webhooks.send('rolagens', { personagem: RPGDesk.doc.get('nome'), total: r.total });
  });
</script>
```

Do outro lado, um Zap com o gatilho **Catch Hook** e a ação de mandar uma mensagem num canal do Discord, usando `data.personagem` e `data.total`.

> **Limites**
>
> Até 20 envios por minuto em cada ficha aberta (passou disso, o `send` falha com um erro) e 30 por minuto na mesa toda. Os dados vão em JSON, até 16 KB; a resposta do serviço volta até 64 KB. No modo de teste, nada sai: o **Registro** mostra o que seria mandado.