Skip to main content

​
Goal

Run long document jobs asynchronously and notify your backend when each job finishes. Use the Legal Filing Platform example or Attention Is All You Need when you want a larger public file for async and webhook testing.

​
Use This Workflow

Use webhooks when jobs may take long enough that polling every few seconds is wasteful or brittle.

​
Setup

1

Create a portal link

Use the webhook portal endpoint to open the provider portal for your organization.
2

Add your endpoint

Configure your HTTPS endpoint in the portal.
3

Verify signatures

Validate webhook signatures before trusting event payloads.
4

Fetch final results

Treat the webhook as a notification. Fetch the canonical job result from GET /job/{jobId}.

​
Minimal Handler Pattern

from flask import Flask, request, jsonify
from pulse import Pulse

app = Flask(__name__)
client = Pulse(api_key="YOUR_API_KEY")

@app.post("/webhooks/pulse")
def pulse_webhook():
    event = request.get_json()
    job_id = event.get("job_id") or event.get("data", {}).get("job_id")

    if not job_id:
        return jsonify({"ok": True})

    job = client.jobs.get_job(job_id=job_id)

    if job.status == "completed":
        # Store job.result in your database or enqueue downstream work.
        pass

    if job.status == "failed":
        # Record the failure and notify your operations path.
        pass

    return jsonify({"ok": True})

​
Production Checklist

  • Respond quickly with a 2xx status.
  • Verify webhook signatures.
  • Make the handler idempotent; the same event may be delivered more than once.
  • Fetch the final job state from Pulse before mutating your database.
  • Use a queue for slow downstream processing.
  • Log job_id, status, and final output IDs.
  • Keep polling fallback logic for recovery and local testing.
  • Persist request metadata such as file_url, config IDs, user ID, and destination record ID so every completed job can be audited.
  • Do not trust webhook payloads alone for regulated writes; verify signatures and fetch the final job result before updating source-of-truth systems.

Webhooks Guide

Full setup and security details.

Poll Job

Polling strategy and result format.