> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks do SDK

> Crie assinaturas de webhook embedded e verifique payloads de eventos assinados

Os webhooks embedded notificam o seu servidor quando ocorre atividade de qualquer usuário final do
seu projeto de parceiro. Cada payload identifica o usuário final afetado para que você possa
direcioná-lo ao cliente correto.

## Criar uma assinatura

Os endpoints de webhook devem usar HTTPS e ser acessíveis publicamente.

```ts theme={null}
const webhook = await soMe.webhooks.create({
  url: "https://app.example.com/webhooks/so-me",
  events: ["post.published", "post.failed"],
});

// Salve este valor imediatamente; ele é retornado apenas na criação.
await secrets.store("some-webhook-secret", webhook.secret!);
```

Omita `events`, ou passe um array vazio, para receber todos os eventos reconhecidos que
ocorrerem para os seus usuários finais embedded.

```ts theme={null}
const subscriptions = await soMe.webhooks.list();
await soMe.webhooks.remove(webhook.id);
```

Eventos úteis para uma integração de publicação embedded incluem:

| Evento | Significado |
| - | - |
| `social.account_connected` | Uma conta social foi conectada |
| `social.account_disconnected` | Uma conta social foi desconectada |
| `post.scheduled` | Um post entrou na fila de publicação |
| `post.published` | A plataforma social aceitou o post |
| `post.failed` | A publicação falhou |

## Verificar a assinatura

O Social media studio assina o corpo exato da requisição HTTP bruta com HMAC-SHA256. Leia o corpo como
texto ou bytes e verifique-o antes de interpretar o JSON.

```ts theme={null}
import {
  verifyWebhookSignature,
  type EmbeddedWebhookEvent,
} from "@social-media-scheduler/sdk";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("x-webhook-signature") ?? "";

  if (
    !verifyWebhookSignature(
      rawBody,
      signature,
      process.env.SOME_WEBHOOK_SECRET!,
    )
  ) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(rawBody) as EmbeddedWebhookEvent;
  await handleEvent(event);
  return new Response(null, { status: 204 });
}
```

A assinatura pode ser enviada como um digest hexadecimal ou com o prefixo `v1=`; o
SDK aceita as duas formas.

## Formato do payload

```json theme={null}
{
  "id": "delivery_uuid",
  "event": "post.published",
  "createdAt": "2026-08-20T10:00:04.000Z",
  "endUser": {
    "id": "end_user_uuid",
    "externalId": "customer_123"
  },
  "data": {
    "postId": "post_uuid",
    "platform": "THREADS"
  }
}
```

As requisições de entrega também incluem:

| Cabeçalho | Descrição |
| - | - |
| `X-Webhook-Signature` | Assinatura HMAC-SHA256 do corpo bruto |
| `X-Webhook-Event` | Nome do evento |
| `X-Webhook-Delivery-Id` | Identificador estável da entrega |

## Comportamento da entrega

* Retorne uma resposta `2xx` assim que o evento for aceito de forma durável.
* Processe os eventos de forma assíncrona quando o trabalho puder levar mais de alguns segundos.
* Deduplique as entregas usando o `id` do payload ou
  `X-Webhook-Delivery-Id`.
* Respostas diferentes de `2xx`, falhas de rede e tempos limite são repetidos com
  espera exponencial.
* Assinaturas que falham repetidamente são desativadas automaticamente.

A entrega de webhooks é "pelo menos uma vez", portanto os handlers devem ser idempotentes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.