Skip to main content

​
Overview

Webhooks let Reap push status updates to your server the moment a video project reaches a final state — no more polling. When a project completes, fails, or expires, Reap sends a POST request to your configured endpoint with the project’s status.

​
How It Works

1

Create a Project

Use the API to create a clipping, captions, reframe, or dubbing project as usual.
2

Processing Begins

Reap processes your video in the background.
3

Project Reaches Final State

The project finishes with a status of completed or invalid.
4

Reap Sends a Webhook

A POST request with the project status is sent to every active webhook URL configured in your studio.
5

Your Server Processes the Event

Your endpoint receives the payload, returns HTTP 200 with an empty body, and handles the event.

​
Webhook Payload

Every webhook delivery sends a JSON POST request with this structure: 
{
  "projectId": "65f1a2b3c4d5e6f7a8b9c0d1",
  "projectType": "clipping",
  "source": "user_upload",
  "status": "completed"
}
​
projectId
string
Unique identifier of the project.
​
projectType
string
Type of project: clipping, captions, reframe, or dubbing.
​
source
string
Source of the original video: youtube, user_upload, or external.
​
status
string
The final status that triggered the webhook.

​
Statuses That Trigger Webhooks

StatusDescription
completedProject finished processing successfully. Clips/results are ready.
invalidThe source video was invalid or processing failed.
expiredProject results expired and are no longer available.
Webhooks are only sent when a project reaches a final state. You will not receive webhooks for intermediate states like processing.

​
Setting Up a Webhook

Webhooks are configured from the Reap dashboard, not via the API.
1

Open Webhook Settings

Log in to your Reap dashboard and navigate to Profile > Settings > Webhooks.
2

Create a New Webhook

Click Create Webhook. Provide a descriptive name and your HTTPS endpoint URL.
3

Validation

Reap sends a test POST request to your URL with the following dummy payload. Your endpoint must return HTTP 200 with an empty response body within 5 seconds.
{
  "projectId": "000000000000000000000000",
  "projectType": "clipping",
  "source": "user_upload",
  "status": "completed"
}
4

Webhook is Active

Once the test passes, the webhook is saved and active. All future project status changes in your studio will be delivered to this endpoint.
Your endpoint must be live and responding correctly before you create the webhook. Reap will reject the webhook if the test request fails.

​
Endpoint Requirements

Your webhook endpoint must meet these requirements:

HTTPS Only

The URL must use HTTPS. HTTP, localhost, and private IP addresses are not allowed.

Accept POST with JSON

Your endpoint must accept POST requests with a Content-Type: application/json body.

Return 200 Empty

Respond with HTTP status 200 and an empty response body. Any other status code is treated as a failure.

Respond Within Timeout

Respond within 5 seconds during webhook creation/validation, and within 10 seconds for live deliveries. Exceeding the timeout counts as a failure.

​
URL Restrictions

Your webhook URL must pass these validation checks:
  • Must use the https:// scheme
  • Cannot point to localhost, 127.0.0.1, or 0.0.0.0
  • Cannot point to private or reserved IP address ranges

​
Example Webhook Receiver

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/reap', (req, res) => {
  const { projectId, projectType, source, status } = req.body;

  // Return 200 immediately with empty body
  res.status(200).send('');

  // Process the event asynchronously
  handleProjectUpdate(projectId, projectType, source, status);
});

async function handleProjectUpdate(projectId, projectType, source, status) {
  if (status === 'completed') {
    // Fetch clips or project details from the API
    console.log(`Project ${projectId} completed. Fetching results...`);
  } else if (status === 'invalid') {
    console.log(`Project ${projectId} failed with status: ${status}`);
  } else if (status === 'expired') {
    console.log(`Project ${projectId} expired.`);
  }
}

app.listen(3000, () => console.log('Webhook receiver running on port 3000'));

​
Managing Webhooks

All webhook management is done from the Reap dashboard under Profile > Settings > Webhooks. You can:
  • Update the name or URL of an existing webhook. Changing the URL triggers a new test request.
  • Disable/Enable a webhook. Re-enabling a disabled webhook triggers a test request to verify your endpoint is working.
  • Delete a webhook to stop receiving notifications permanently.
  • View delivery history for each webhook, including response codes and delivery times.
All active webhooks in a studio receive notifications for every project in that studio. You cannot scope a webhook to specific project types.

​
Auto-Disable on Failures

Reap tracks consecutive delivery failures for each webhook:
  • Each failed delivery (non-200 response, timeout, or unreachable endpoint) increments the failure counter.
  • After 5 consecutive failures, the webhook is automatically disabled and you are notified via email.
  • Any successful delivery resets the failure counter back to 0.
To re-enable a disabled webhook:
  1. Fix the issue with your endpoint
  2. Go to Profile > Settings > Webhooks in the dashboard
  3. Toggle the webhook back on (this triggers a test request)
There are no automatic retries. If a delivery fails, Reap logs the failure and moves on. Design your system to handle missed events by periodically checking Get Project Status for critical projects.

​
Plan Limits

PlanMax Active Webhooks
Free0 (no webhook access)
Creator1
Studio5
Need more webhooks? Contact us to discuss enterprise options.

​
Best Practices

Respond Fast

Return 200 immediately and process the event asynchronously. Don’t do heavy work before responding.

Handle Duplicates

Design your handler to be idempotent. In rare cases, you may receive the same event more than once.

Monitor Deliveries

Check webhook delivery history in your dashboard regularly to catch issues before the auto-disable threshold.

Have a Fallback

Use Get Project Status as a fallback for critical workflows in case a webhook delivery is missed.

​
Next Steps