Webhooks

Webhooks push events to your server so you don’t have to poll. They’re the reliable way to learn the outcome of scheduled posts and asynchronous (video) uploads. Create a webhook endpoint from your dashboard at hub.madiad.com/dashboard/webhooks: enter the URL that should receive deliveries and pick the events you want. The dashboard generates a secret for that endpoint — store it. You’ll use it to verify every delivery.

Events

Event	Fires when
`post.completed`	An upload finished processing on a platform — success or failure is in the payload
`connection.connected`	A social account was linked to a profile
`connection.disconnected`	A social account was unlinked from a profile
`connection.reauth_required`	A connected account needs to be re-authorized

Each delivery is a JSON body shaped { "id", "type", "created_at", "data": { … } }. For post.completed, data carries profile_id, platform, media_type, success, draft, url, publish_id, and error. draft: true means the platform took the post into the account’s drafts instead of publishing it (most often TikTok, at its daily limit on direct posts): success is still true, url is null, and the post is not live until the account owner publishes it in the app. Treat it as not published, and do not retry it.

Verify the signature

Every request carries an X-MADIAD-Signature header in the form sha256=<hex>: an HMAC-SHA256 of the raw request body, keyed with your subscription secret. Recompute it and compare before trusting the payload. Each delivery also includes X-MADIAD-Event and X-MADIAD-Delivery headers.

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Verify against the raw, unparsed body. Re-serializing parsed JSON changes the bytes and the signature will not match.

Respond and retries

Return a 2xx status within 5 seconds to acknowledge receipt. Redirects are not followed, so a 3xx counts as a failure.
Any non-2xx response or a timeout fails the attempt. Each attempt makes up to 3 quick tries, 0.5 s and then 1 s apart.
A delivery gets up to 5 attempts. After a failed attempt the next one waits at least 1 minute, then 5 minutes, then 30 minutes, then 2 hours. Retries run in background passes, so the real gap can be longer — at the latest the daily pass at 01:30 UTC picks the delivery up.
After the 5th failed attempt the delivery is marked dead and is not sent again.
Make your handler idempotent — a delivery can arrive more than once. Dedupe on the delivery id (also sent as the X-MADIAD-Delivery header).

Do slow work (database writes, downstream calls) after you respond 2xx — for example by enqueueing the event — so you never trip the delivery timeout.

Get Started

Concepts

Integrations

API Reference

Events

Verify the signature

Respond and retries

​Subscribe

​Events

​Verify the signature

​Respond and retries

Subscribe

Events

Verify the signature

Respond and retries