The Price API Webhook feature provides customers with the capability to receive real-time notifications when their jobs are completed. By specifying a webhook URL and other parameters, customers can integrate PriceAPI seamlessly into their workflows and access job results efficiently.

Webhook Endpoint

To enable the Price API Webhook feature, customers need to provide a Webhook URL where they want to receive notifications. When the started job is completed, a request will be sent to this URL. The Webhook URL is specified using the webhook_url parameter.

Input Parameters

webhook_url (string, optional): The URL where the webhook notifications will be sent. Customers must provide this URL to enable webhook notifications. Example: https://yourdomain.com/yourapp/webhookurl.

webhook_method (string, optional, default: POST): This parameter allows customers to specify the HTTP request method for sending webhook notifications. By default, a POST request is used. However, customers can override this with other HTTP methods such as PUT or GET if required by their platform.

webhook_download_format (string, optional, default: json): This parameter defines the output format for which the Price API will include the download_url in the webhook body. Customers can specify different output formats depending on their preferences and requirements. All supported download formats per source/topic can be requested via the download_formats endpoint. Alternatively, all available download formats can also be reviewed in the Price API Requester.

Supported Webhook Methods

POST (default): A POST request will be made to the webhook_url when the job is completed. The webhook payload will contain job-related information.

PUT: A PUT request can be specified using the webhook_method parameter. If selected, a PUT request will be made to the webhook_url when the job is completed.

GET: A GET request can be specified using the webhook_method parameter. If selected, a GET request will be made to the webhook_url when the job is completed. However, note that the use of GET requests for webhooks may not be suitable for all scenarios and is less common than POST and PUT requests.

Webhook Response

When the started job is completed, Price API will send a JSON response to the specified webhook_url.
The JSON response will contain the following key-value pairs:

job_id: A unique identifier for the completed job.
download_url: A URL pointing to the results of the completed job. The format of this URL depends on the webhook_download_format specified by the customer.

Here is an example of the webhook response:

{
  "payload": {
    "product": "priceapi",
    "topic": "job",
    "event": "finished",
    "user_id": "abcdef12345678eabc",
    "job_id": "bca32114a25cde",
    "version": "v2",
    "job_download_url": "https://example.com/results/12345.json"
  },
  "meta": {
    "system": "priceapi-api",
    "sent_at": 1697108049
  }
}

Error Handling

To handle errors when receiving webhook notifications, Price API employs the following strategy:

PriceAPI retries webhook notifications after progressively increasing intervals upon receiving an HTTP status code different from 200.

The retry intervals follow roughly an exponential pattern: 1 minute, 2 minutes, 4 minutes, 8 minutes, and so on, up to a maximum of 10 retries (512 minutes or approximately 8.5 hours).

This error handling strategy ensures that webhook notifications are retried in case of temporary issues, such as network disruptions, to maximize the chances of successful delivery.

🚧
Security Considerations
When working with webhooks and callbacks, it's essential to consider security to protect your application and data. Here are some basic security guidelines to follow on your end:

Use HTTPS for webhook URLs to encrypt data transmission

Implement authentication and authorization mechanisms

Validate webhook payloads to prevent tampering

Whitelist IP addresses to restrict access to trusted sources

Implement rate limiting to prevent abuse

Set up logging and monitoring for suspicious activity

Ensure secure coding practices for webhook handling code