Skip to content

Webhooks Overview

Webhooks allow your application to receive real-time notifications when events occur in the Fixify platform. Instead of polling the API for changes, you configure an endpoint that Fixify will send HTTP POST requests to whenever relevant events happen.

How It Works

  1. Configure — Set up a webhook URL via the API and select which event types you want to receive
  2. Receive — When an event occurs, Fixify sends a signed HTTP POST to your endpoint
  3. Verify — Validate the HMAC-SHA256 signature to ensure the request is authentic
  4. Respond — Return a 2xx status code to acknowledge receipt
┌──────────┐        ┌──────────────┐        ┌──────────────┐
│  Fixify  │──POST──▶  Cloud Tasks  │──POST──▶  Your Server │
│ Platform │        │   (queued)   │        │  (webhook)   │
└──────────┘        └──────────────┘        └──────────────┘

Quick Start

1. Configure your webhook endpoint

curl -X PUT https://api.fixify.co.za/v1/agency/webhooks/config \
  -H "authorization: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhooks/fixify",
    "enabled": true,
    "subscribedEventTypes": ["job_created", "job_completed"]
  }'

The response includes a signingSecret — store this securely for signature verification.

2. Implement your endpoint

Your endpoint must:

  • Accept POST requests with Content-Type: application/json
  • Return a 2xx response within 10 seconds
  • Verify the X-Fixify-Signature header (recommended)

3. Verify signatures

Use the signing secret to verify that incoming requests are genuine. See Signature Verification for implementation examples.

Requirements

Requirement Details
Protocol HTTPS only (HTTP not accepted)
Response time Must respond within 10 seconds
Response code Any 2xx is treated as success
Public endpoint Must be reachable from the internet (no private IPs)

Scope

Webhooks are configured at the agency level. Each agency has one webhook configuration that receives events for all entities belonging to that agency.

Next Steps