Help Center

  • Fill out my online form
  • What are pingbacks & postbacks and how to use them with DataForSEO API?

    Commonly, pingback is known as a callback function, and postback is referred to as a webhook or HTTP push. With DataForSEO API, the pingback function is like a notification sent to your server upon the completion of a task, while postback is a function that actually sends the results to your server.

    When you download examples for a necessary programming language from our documentation, you will find pingback_example and postback_example files in the folder.

    How to set a task with the pingback option?

    1. Store the file (e.g. pingback_example.php) on your server.
    2. When setting a task, specify the path to the Pingback file on your server in the pingback_url parameter.

    3. Example:

      http://your-server.com/pingscript?id=$id
      http://your-server.com/pingscript?id=$id&tag=$tag
      

    4. Once the task is completed, a new file will be created on your server containing the ID of the completed task(s) and your parameter specified in the “tag” field.

    How to set a task with the postback option?

    1. Store the file (e.g. postback_example.php) on your server.
    2. When setting a task, specify the path to the Postback file on your server in the postback_url parameter.

    3. Example:

      http://your-server.com/postbackscript?id=$id
      http://your-server.com/postbackscript?id=$id&tag=$tag
      

    4. Iin SERP API and Merchant API v3, you also need to specify a postback_data parameter indicating the type of results you wish to receive (regular, advanced, html).
    5. Once the task is completed, we will send a POST request with the results of the task compressed in the gzip format to the path you specified in the “postback_url” field. In other words, a new file will be created on your server containing the actual results of the task(s) you have set.
    6. Note 1: In case of any issues on your server’s or database’s side that prevented you from receiving pingbacks/postbacks from our system, you can resend them using the Webhook Resend endpoint. When calling this endpoint, you can specify up to 100 task IDs. You won’t be double-charged for resending pingbacks/postbacks or for using this function.

      Note 2: IDs of the tasks set with the “postback_url” parameter will not be provided in the list of completed tasks by the corresponding Tasks Ready endpoint.

      You can learn more about using Pingbacks and Postbacks in DataForSEO from the video tutorial blelow. Note that the tutorial is based on DataForSEO API v2, however it provides a detailed explanation of the main concepts and gives sufficient instructions that can be applied to making API requests in v3 as well.