Webhooks Reference

How they work

Webhook URLs will receive a POST request with JSON data related to the event that triggered the webhook.

See Events below for supported events and the associated JSON payloads.

Error handling

There are things that can go wrong even before a request reaches its destination (e.g. DNS resolution error, sudden network failure, etc.) and even if it does, the target system may not always be able to correctly process the request. This is why the notification delivery system is built to handle these failures.

Our webhook delivery system uses response status to determine whether a request has been successful or not.

• 2XX response codes: The request is considered successful and the notification is considered as delivered, no retry needed.

• Any other response status or error (such as connection error, timeout, etc.) is handled as an unsuccessful delivery attempt and the task is rescheduled for later.

Retries

If a webhook delivery fails, it gets retried. We use an exponential backoff strategy to determine how long to wait before attempting the delivery again.

We'll retry a webhook delivery up to 20 times, after which the delivery will be marked as retries exhausted and retries will stop.

Events

screenshot_set.approved

This event is fired when a set of screenshots is ready for download

Payload

{
  "id": "evt_{{uuid-of-event}}", // unique ID for this event
  "type": "event",
  "created_at": "2023-01-01T10:52:11.822-05:00",
  "topic": "screenshot_set.approved",
  "data": {
    "object": {
      "type": "screenshot_set",
      "id": "uuid-of-screenshot-set",
      "campaign_id": "uuid-of-campaign", // ID of the Campaign in Ad Reform
      "created_at": "2023-01-01T10:51:23.961-05:00",
      "status": "approved", // this will always be "approved"
      "instructions": "",   // the special instructions sent in the original request
      "review_notes": "",   // notes from Ad Reform if there was a problem with the screenshot
      "screenshots": [
        {
          "type": "screenshot",
          "id": "uuid-of-screenshot", // ID of the Screenshot in Ad Reform
          "status": "uploaded",
          "image_url": "https://app.adreform.com/path/image.png",
          "device": "Desktop",
          "site": {
            "url": "https://theverge.com",
            "host": "theverge.com"
          },
          "ad": {
            "type": "ad",
            "id": "uuid-of-ad", // ID of the Ad in Ad Reform
            "status": "uploaded",
            "lookup_key": "ad-lookup-key-if-present", // or null
            "name": "name-if-present", // name of the Ad in Ad Reform
            "external_id": null,
            "preview_image_url": "https://app.adreform.com/path/image.png",
            "width": 300,
            "height": 250,
            "html_url": "https://app.adreform.com/path/to/ad/in-webui",
            "media": {
              "type": "image_file" // see Media object in docs for possible values
            },
            // if ad was synced from Xandr, this will be present
            "xandr_creative": {
              "xandr_id": 440600236,
              "name": "ad_reform_300x250",
              "line_item": {
                "xandr_id": 21352428,
                "name": "Example Display-EN_O6X6TSIFL-1261",
                "state": "active"
              }
            }
          },
          // if a bucket and key_prefix were specified
          // as `subscribers` in the Screenshot Request
          // we'll include info about the S3 objects here
          "s3_objects": [
            {
              "bucket": "my-bucket-name",   // bucket containing the screenshot
              "key": "key-prefix/uuid.png", // object key for the screenshot
              "status": "uploaded"          // will be "upload_failed" if there was a problem uploading
            }
          ]
        },
        {
          "type": "screenshot",
          "id": "uuid",
          "status": "uploaded",
          "image_url": "https://app.adreform.com/path/image2.png",
          "device": "Desktop",
          "site": {
            "url": "https://espn.com",
            "host": "espn.com"
          },
          "ad": {
            "id": "uuid-of-ad",
            "status": "uploaded",
            "lookup_key": "ad-lookup-key-if-present",
            "type": "ad",
            "name": "name-if-present",
            "external_id": null,
            "preview_image_url": "https://app.adreform.com/path/image.png",
            "width": 300,
            "height": 250,
            "html_url": "https://app.adreform.com/path/to/ad/in-webui",
            "media": {
              "type": "image_file"
            }
          },
          "s3_objects": [
            {
              "bucket": "my-bucket-name",
              "key": "key-prefix/uuid.png",
              "status": "uploaded"
            }
          ],
          "xandr_creative": null
        }
      ]
    }
  }
}

Objects

ad

This object contains data about the ad creative. Notable fields include:

status

Status	Description
uploaded	The ad creative was captured successfully
not_found	We couldn't find the creative asset when loading the ad
net_read_timeout	We encountered network issues when loading the ad
generic_error	We encountered an error when loading the ad

screenshot

This object contains data about the screenshot. Notable fields include:

status

Status	Description
uploaded	The screenshot was generated successfully
ad_not_captured	The associated ad was not captured so the screenshot cannot be generated
net_read_timeout	We encountered network issues when generating the screenshot
no_slots_found	The requested site had no ad slots matching the associated ad dimentions
site_unreachable	The requested site was not reachable
ssl_error	We encountered an SSL error when generating the screenshot
generic_error	We encountered an error when capturing the screenshot