Webhooks

Tickaroo uses webhooks to notify your application when an event happens in your organization. Webhooks are particularly useful for realtime liveblog updates.

Events

ticker_update

This event is triggered with every liveblog update within your organization. Each subscribed endpoint will be called with a POST request.

Payload:

{
  "event_type": "ticker_update",
  "ticker_id": "YOUR_TICKER_ID",
  "local_id": "YOUR_TICKER_LOCAL_ID",
  "version": "CURRENT_TICKER_VERSION"
}

API Endpoints

Subscribe

Request: POST /apigw/webhooks/v2/organization/{organizationId}/subscribe

Path Parameters:

  • organizationId: The organization to subscribe to

Query Parameters (for authentication):

  • client_id: Your client ID
  • client_secret: Your client secret

Request Body:

{
  "url": "https://your-webhook-endpoint.com/path"
}

Success Response: 200 OK

Unsubscribe

Request: POST /apigw/webhooks/v2/organization/{organizationId}/unsubscribe

Path Parameters:

  • organizationId: The organization to unsubscribe from

Query Parameters (for authentication):

  • client_id: Your client ID
  • client_secret: Your client secret

Request Body:

{
  "url": "https://your-webhook-endpoint.com/path"
}

Success Response: 200 OK

List Subscriptions

Request: GET /apigw/webhooks/v2/organization/{organizationId}/list

Path Parameters:

  • organizationId: The organization with subscriptions

Query Parameters (for authentication):

  • client_id: Your client ID
  • client_secret: Your client secret

Success Response:

{
  "webhooks": [
    {
      "url": "https://webhook1.example.com",
      "status": "active",
      "lastOutcome": {
        "timestamp": "2023-06-15T14:22:33.456Z",
        "success": true,
        "statusCode": 200,
        "message": "Successfully sent webhook notification"
      },
      "consecutiveFailures": 0,
      "consecutiveFailureSince": null
    },
    {
      "url": "https://webhook2.example.com",
      "status": "disabled",
      "lastOutcome": {
        "timestamp": "2023-06-15T10:15:22.123Z",
        "success": false,
        "statusCode": 500,
        "message": "Internal server error"
      },
      "consecutiveFailures": 12,
      "consecutiveFailureSince": "2023-06-08T09:45:11.789Z"
    }
  ]
}

Retry Behaviour

  • On network errors, timeouts and 5xx responses webhooks are retried up to three times with delays ranging from 100ms to 900ms.
  • After three retries or on any other error (e.g. 4xx errors) a new delivery attempt is scheduled every 10 minutes
  • After 12 delivery attempts, the message is marked as failed and no further delivery attempts take place

Webhook Reliability

Webhooks are automatically disabled after 10 consecutive failures over a period of at least 7 days. This helps prevent unnecessary load on both systems when a webhook endpoint is consistently failing.

To re-enable a disabled webhook, simply resubscribe with the same URL.

Each webhook delivery attempt is recorded. You can view the status and last outcome of each webhook using the List Subscriptions endpoint.