Webhooks

Receive real-time notifications when your content generation is complete instead of polling the status endpoint.

How Webhooks Work

Include webhook_url in your create request
GenRex queues your request and begins processing
When complete (success or failure), we send a POST request to your URL
Your server acknowledges with a 2xx status code

Setting Up Webhooks

Add webhook_url to any create request:

curl -X POST https://api.genrex.io/v1/document/create \
  -H "Authorization: Bearer grx_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Best practices for API design",
    "webhook_url": "https://yoursite.com/webhooks/genrex"
  }'

Webhook Payload

We send a POST request with the following structure:

Success Payload

{
  "event": "document.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "data": {
    "title": "Best Practices for API Design",
    "description": "A comprehensive guide to designing...",
    "featured_image": "https://genrex.io/images/featured/...",
    "content": { ... },
    "word_count": 2150,
    "reading_time": "11 min read"
  },
  "delivery": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "post_status": "draft",
    "metadata": {
      "categories": ["Technology"],
      "tags": ["api", "design"]
    }
  }
}

The delivery object is only included when the request specified a site_id. It contains the post status and metadata (categories, tags) for the connected site. This applies to both immediate and scheduled generations.

Failure Payload

{
  "event": "document.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": {
    "step": "generating",
    "message": "Content was flagged by moderation policy",
    "code": "CONTENT_MODERATION"
  }
}

Event Types

Event	Description
`document.completed`	Document generation completed
`document.failed`	Document generation failed
`research.completed`	Research completed
`research.failed`	Research failed
`text.completed`	Text generation completed
`text.failed`	Text generation failed
`image.completed`	Image generation completed
`image.failed`	Image generation failed
`audio.completed`	Audio generation completed
`audio.failed`	Audio generation failed

Retry Logic

If your endpoint fails to respond with a 2xx status, we retry with exponential backoff:

Attempt	Delay
Initial attempt	Immediate
1st retry	5 minutes
2nd retry	15 minutes
3rd retry (final)	30 minutes

After 4 attempts, the webhook is marked as failed but the prompt result remains available via the status endpoint.

Handling Webhooks

PHP / Laravel

Route::post('/webhooks/genrex', function (Request $request) {
    $event = $request->input('event');
    $id = $request->input('id');

    if (str_ends_with($event, '.completed')) {
        $data = $request->input('data');
        // Process the completed content
        // Store in database, publish to CMS, etc.
    } else {
        $error = $request->input('error');
        // Handle the failure
        Log::error("GenRex generation failed", [
            'id' => $id,
            'error' => $error
        ]);
    }

    return response()->json(['received' => true]);
});

Node.js / Express

app.post('/webhooks/genrex', (req, res) => {
  const { event, id, data, error } = req.body;

  if (event.endsWith('.completed')) {
    // Process the completed content
    console.log('Content ready:', data);
  } else {
    // Handle the failure
    console.error('Generation failed:', error);
  }

  res.json({ received: true });
});

Best Practices

Respond quickly (within 5 seconds) and process asynchronously
Use HTTPS endpoints only
Handle duplicate deliveries (webhooks may be sent more than once)
Store the id to correlate with your original request