Use incoming webhooks to get real-time updates

Listen for events on your Ovoko account so your integration can automatically trigger reactions.
Ovoko uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events to get part status change information.

How Ovoko uses webhooks

A webhook enables Ovoko to push real-time notifications to your app. Ovoko uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Steps to receive webhooks

  1. Identify the events you want to monitor and the event payloads to parse.
  2. Create a webhook endpoint as an HTTP endpoint (URL).
  3. Handle requests from Ovoko by parsing each event object and returning 2xx response status codes.
  4. Secure your webhooks.
  5. Provide your publicly accessible HTTPS URL to us.

How to create a webhook endpoint

Creating a webhook endpoint is no different from creating any other page on your website. It’s an HTTP or HTTPS endpoint on your server with a publicly accessible URL. You have to use one endpoint to handle several different event types at once.

Step 1: Identify the events to monitor

Use the Events reference guide to identify the Ovoko events and their event objects your webhook endpoint needs to parse.

Step 2: Create a webhook endpoint

Set up an HTTP endpoint that can accept webhook requests with a POST method.

Step 3: Handle request from Ovoko

Your endpoint must be configured to read event objects for the type of event notifications you want to receive. Ovoko sends events to your webhook endpoint as part of a POST request with a JSON payload.
Check event objects:
Each event is structured as an event object with an event_type, event_id, and related event_data. Your endpoint must check the event type and parse the payload of each event. 
{
    "event_id": "101aa6a1-ed22-42f0-84ca-1f8a028a2d28",
    "event_type": "part.status.changed",
    "timestamp": "2023-01-12T14:17:20+02:00",
    "event_data": {
          "part_id": "15",
          "status": "sold",
    }
}
Return a 2xx response
Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout.

Step 4: Secure your webhooks (Recommended).

To ensure that webhook requests are secure and originate from Ovoko, implement header token authorization. You can create any custom header and value in your application to verify the authenticity of the webhook requests. This typically involves including a secret token in the header of your webhook requests that your application will check upon receiving the webhook. Ensure that this token is known only to your application and Ovoko.
Request curl example: 
curl -X POST [callback_url] \
-H "[callback_header_name]: [callback_header_value]" \
-H "Content-Type: application/json" \
-d '{
     "event_id": "101aa6a1-ed22-42f0-84ca-1f8a028a2d28",
     "event_type": "part.status.changed",
     "timestamp": "2023-01-12T14:17:20+02:00",
     "event_data": {
          "part_id": "15",
          "status": "sold"
     }
}'

Step 5: Provide your webhook URL to start receiving events.

To start receiving events, you need to register your webhook URL. Go to your Scrapyard account, then navigate to Settings > Integrations > API . Enter your callback URL and the custom headers you've configured for authorization. This ensures that your endpoint is ready to receive and verify event notifications from Ovoko.