Overview

Webhooks let you receive real-time HTTP notifications when events happen in your account. Instead of polling the API for changes, you register a URL and we’ll send a POST request to it whenever a relevant event is triggered.

Setting up a webhook

To get started, use the Create webhook endpoint to register a webhook URL (must be HTTPS and not an IP).

curl -X POST https://api.engine.usesophic.com/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/sophic"
  }'

Webhook events

We deliver every event type to each active webhook in your account.

Webhook headers

Every webhook delivery includes the following HTTP headers:

Header	Description
`Content-Type`	Always `application/json`.
`Webhook-Id`	The unique ID of this delivery (e.g. `whd_abc123`). Use this to deduplicate retried deliveries.
`Webhook-Timestamp`	Unix timestamp (seconds) of when the delivery was dispatched. Use this to reject stale messages.
`Webhook-Signature`	HMAC-SHA256 signature(s) of the payload. Multiple signatures may be present during secret rotation.
`Webhook-Attempt`	1-indexed attempt number for this delivery. `1` on the first try, incremented on each retry.
`Event-Id`	The ID of the originating event (e.g. `evt_abc123`).

Receiving webhooks

When an event occurs, we send a POST request to your registered URL. The webhook payload follows the same schema as the Event resource:

{
  "id": "evt_abc123",
  "name": "order.filled",
  "resource": {
    "id": "ord_xyz789",
    "resource_type": "order"
  },
  "data": {},
  "created_at": "2026-01-15T10:30:00Z"
}

Events do not carry resource data in the payload. The data field is always empty. Use resource.id to fetch the resource and get its latest state. See Events for the full list of event types. Your endpoint should return a 2xx status code within 15 seconds to acknowledge receipt. Any other status code, timeout, or connection error is treated as a failed delivery and will be retried. The maximum time we’ll wait for a response is 25 seconds (5s connect + 15s read + 5s write).

CSRF protection

If you use Rails, Django, or another web framework, your site might automatically check that every POST request contains a CSRF token. This is an important security feature, but it can also prevent your site from processing legitimate webhook events. If so, you may need to exempt your webhook route from CSRF protection.

from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST

@require_POST
@csrf_exempt
def webhook(request):
    # Process webhook payload
    ...

class WebhooksController < ApplicationController
  protect_from_forgery except: :handle

  def handle
    # Process webhook payload
  end
end

@RestController
@RequestMapping("/webhooks")
public class WebhookController {
    // Spring Security: configure your SecurityFilterChain
    // to disable CSRF for the webhook endpoint.
    //
    //   http.csrf(csrf -> csrf
    //       .ignoringRequestMatchers("/webhooks/**")
    //   );

    @PostMapping
    public ResponseEntity<Void> handle(@RequestBody String body) {
        // Process webhook payload
        return ResponseEntity.ok().build();
    }
}

// In Program.cs, configure the antiforgery middleware
// to skip your webhook route:
//
//   app.MapPost("/webhooks", [IgnoreAntiforgeryToken] async (HttpContext ctx) =>
//   {
//       // Process webhook payload
//   });

Getting Started

Onboarding

Orders

Webhooks

Setting up a webhook

Webhook events

Webhook headers

Receiving webhooks

CSRF protection

​Setting up a webhook

​Webhook events

​Webhook headers

​Receiving webhooks

​CSRF protection

Setting up a webhook

Webhook events

Webhook headers

Receiving webhooks

CSRF protection