> ## 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 del SDK

> Crea suscripciones de webhooks embebidos y verifica las cargas de eventos firmadas

Los webhooks embebidos avisan a tu servidor cuando ocurre actividad para cualquier usuario final de
tu proyecto de socio. Cada carga identifica al usuario final afectado para que puedas
dirigirla al cliente correcto.

## Crear una suscripción

Los endpoints de webhook deben usar HTTPS y ser accesibles públicamente.

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

// Save this value immediately; it is returned only on creation.
await secrets.store("some-webhook-secret", webhook.secret!);
```

Omite `events`, o pasa un arreglo vacío, para recibir todos los eventos reconocidos que
ocurran para tus usuarios finales embebidos.

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

Estos son eventos útiles para una integración de publicación embebida:

| Evento | Significado |
| - | - |
| `social.account_connected` | Se conectó una cuenta social |
| `social.account_disconnected` | Se desconectó una cuenta social |
| `post.scheduled` | Una publicación entró en la cola de publicación |
| `post.published` | La red social aceptó la publicación |
| `post.failed` | La publicación falló |

## Verificar la firma

Social media studio firma con HMAC-SHA256 el cuerpo HTTP exacto y sin procesar de la solicitud. Lee el cuerpo como
texto o bytes y verifícalo antes de analizar el 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 });
}
```

La firma puede enviarse como un resumen hexadecimal o con el prefijo `v1=`; el
SDK acepta ambas formas.

## Estructura de la carga

```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"
  }
}
```

Las solicitudes de entrega también incluyen:

| Cabecera | Descripción |
| - | - |
| `X-Webhook-Signature` | Firma HMAC-SHA256 del cuerpo sin procesar |
| `X-Webhook-Event` | Nombre del evento |
| `X-Webhook-Delivery-Id` | Identificador de entrega estable |

## Comportamiento de la entrega

* Devuelve una respuesta `2xx` en cuanto el evento se haya aceptado de forma duradera.
* Procesa los eventos de forma asíncrona cuando el trabajo pueda tardar más de unos segundos.
* Deduplica las entregas usando el `id` de la carga o
  `X-Webhook-Delivery-Id`.
* Las respuestas distintas de `2xx`, los fallos de red y los tiempos de espera agotados se reintentan con
  espera exponencial.
* Las suscripciones que fallan repetidamente se deshabilitan automáticamente.

La entrega de webhooks es de al menos una vez, así que los manejadores deben ser idempotentes.


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