Back to Docs
Integrations

Outbound Webhooks

Collab can send an HTTP request to your server when something happens in your challenges. There is no public REST API: webhooks are the integration surface.

How delivery works

Add an endpoint URL, choose its events and optionally set a signing secret at /dashboard/webhooks.

Each event is sent as an HTTP POST with a JSON body. The body is the event payload shown below, with a top-level unix timestamp (seconds) added at send time for replay protection. Respond with any 2xx status to acknowledge it.

Request headers
Content-TypeAlways application/json.
X-Webhook-EventThe event type, for example submission.approved.
X-Webhook-VersionThe payload version. Currently v1.
X-Idempotency-KeyIdentifies the event. Store it and skip any key you have already processed.
X-Webhook-SignatureSent when the endpoint has a signing secret. Lowercase hex HMAC-SHA256 of the raw request body, keyed with your signing secret. No sha256= prefix.
x-newfans-signatureThe same value as X-Webhook-Signature, for older receivers.
X-Webhook-TimestampSent with the signature. The time the request was signed (ISO 8601). Informational: use the signed timestamp in the body for replay checks.

Retries

A delivery that fails (non-2xx response, timeout or network error) is retried with exponential backoff, waiting at most 5 minutes between attempts, until it has failed 5 times. Because of retries the same event can arrive more than once, so de-duplicate on X-Idempotency-Key. Every attempt and its result is listed at /dashboard/webhooks/deliveries.

Events & payloads

Three events are sent today. Fields that have no value may be missing from the payload, so treat every field other than event_type, idempotency_key and timestamp as optional.

submission.approved

An entry to one of your challenges is approved.

Example body
{
  "version": "v1",
  "event_type": "submission.approved",
  "occurred_at": "2026-10-01T18:04:12.511Z",
  "idempotency_key": "submission.approved:6c1f0e1a-2b7d-4a49-9f0c-1f2a3b4c5d6e:2026-10-01T18:04:12.511Z",
  "org_id": "0b9e7c52-3d2f-4f7e-8a51-5c8f2d1e9a10",
  "challenge_id": "a3d5e7f9-1b2c-4d6e-8f0a-1c3e5a7b9d2f",
  "challenge_title": "Open Verse: Midnight Drive",
  "entrant": {
    "user_id": "f4e3d2c1-b0a9-4876-9543-210fedcba987",
    "handle": "lena.writes",
    "email": "lena@example.com",
    "instagram_handle": "@lena.writes"
  },
  "submission": {
    "entry_id": "6c1f0e1a-2b7d-4a49-9f0c-1f2a3b4c5d6e",
    "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "youtube_video_id": "dQw4w9WgXcQ",
    "submitted_at": "2026-09-29T21:15:40.000Z",
    "approved_at": "2026-10-01T18:04:12.511Z"
  },
  "source": "newfans_collab_challenge",
  "timestamp": 1790877853
}
challenge.created

One of your challenges goes live.

Example body
{
  "version": "v1",
  "event_type": "challenge.created",
  "occurred_at": "2026-09-20T15:00:03.120Z",
  "idempotency_key": "challenge.created:a3d5e7f9-1b2c-4d6e-8f0a-1c3e5a7b9d2f:2026-09-20T15:00:03.120Z",
  "org_id": "0b9e7c52-3d2f-4f7e-8a51-5c8f2d1e9a10",
  "challenge": {
    "challenge_id": "a3d5e7f9-1b2c-4d6e-8f0a-1c3e5a7b9d2f",
    "title": "Open Verse: Midnight Drive",
    "genres": [
      "hip-hop",
      "r&b"
    ],
    "status": "live",
    "end_at": "2026-10-20T23:59:00.000Z",
    "is_free_start": false
  },
  "assets": {
    "beat_url": "https://.../beat.mp3",
    "cover_url": "https://.../cover.jpg"
  },
  "public_url": "https://collab.newfanspro.com/challenge/a3d5e7f9-1b2c-4d6e-8f0a-1c3e5a7b9d2f",
  "source": "newfans_collab_challenge",
  "timestamp": 1790002804
}
winner.selected

You pick a winner for one of your challenges.

Example body
{
  "version": "v1",
  "event_type": "winner.selected",
  "occurred_at": "2026-10-21T10:12:45.300Z",
  "idempotency_key": "winner.selected:9e8d7c6b-5a49-4382-a1b0-c9d8e7f6a5b4:https://example.com/hooks/collab",
  "challenge_id": "a3d5e7f9-1b2c-4d6e-8f0a-1c3e5a7b9d2f",
  "winner_log_id": "9e8d7c6b-5a49-4382-a1b0-c9d8e7f6a5b4",
  "entry_id": "6c1f0e1a-2b7d-4a49-9f0c-1f2a3b4c5d6e",
  "winner_handle": "lena.writes",
  "push_to_app": true,
  "featured": false,
  "timestamp": 1792491166
}

Verifying signatures

When an endpoint has a signing secret, compute HMAC-SHA256 over the raw request body with that secret, hex-encode it in lowercase, and compare it to X-Webhook-Signature with a constant-time comparison. Then reject any request whose body timestamp is more than 5 minutes from your clock.

// Node.js (Express). Verify BEFORE parsing the JSON.
const crypto = require('crypto');
const express = require('express');

const app = express();
const SIGNING_SECRET = process.env.COLLAB_WEBHOOK_SECRET;
const MAX_AGE_SECONDS = 5 * 60;

// express.raw keeps the exact bytes Collab signed.
app.post('/hooks/collab', express.raw({ type: 'application/json' }), (req, res) => {
  const received = req.get('X-Webhook-Signature') || '';
  const expected = crypto
    .createHmac('sha256', SIGNING_SECRET)
    .update(req.body) // the raw Buffer, not a re-serialized object
    .digest('hex');

  const a = Buffer.from(received, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('bad signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));

  // The body carries a unix timestamp that is covered by the signature.
  const age = Math.floor(Date.now() / 1000) - Number(event.timestamp);
  if (!Number.isFinite(age) || age > MAX_AGE_SECONDS || age < -MAX_AGE_SECONDS) {
    return res.status(401).send('stale request');
  }

  // Deliveries can repeat: de-duplicate on the idempotency key.
  const key = req.get('X-Idempotency-Key');
  // if (await alreadyProcessed(key)) return res.sendStatus(200);

  switch (event.event_type) {
    case 'submission.approved':
    case 'challenge.created':
    case 'winner.selected':
      // handle it
      break;
  }

  res.sendStatus(200);
});

Sign the bytes you received

Parsing the JSON and serializing it again can change spacing or key order, and the signature will not match. Always hash the raw body exactly as it arrived. Without a signing secret, requests are unsigned, so set one for any endpoint that acts on what it receives.

Need help with integration?

Set up an endpoint and watch its deliveries, or ask our support team.