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.
Content-Type | Always application/json. |
X-Webhook-Event | The event type, for example submission.approved. |
X-Webhook-Version | The payload version. Currently v1. |
X-Idempotency-Key | Identifies the event. Store it and skip any key you have already processed. |
X-Webhook-Signature | Sent 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-signature | The same value as X-Webhook-Signature, for older receivers. |
X-Webhook-Timestamp | Sent 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.approvedAn entry to one of your challenges is approved.
{
"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.createdOne of your challenges goes live.
{
"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.selectedYou pick a winner for one of your challenges.
{
"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.