Webhooks

Didimo uses webhooks to notify your application about specific user-relevant events.
Currently webhooks are only available for three didimo generation related events: processing start, processing failed and processing completed.

Configure webhooks

Setting up webhooks consists of two main steps:

Create a webhook endpoint
Configure your webhook endpoint on your application on Customer Portal

Create a webhook endpoint

You should start by creating a new endpoint that accepts requests from Didimo servers using your technology of choice.
For each event occurrence, Didimo will POST a JSON message, through HTTPS, containing all of the event's context information to your configured endpoint.
Didimo events include an event_type, a context where you can check which API Key was used to generate the request and a data attribute, which will include a representation of the didimo object, just like the one you would get from Gets a didimo by its key.
An example of such messages could be found bellow:

{
  "__type": "WebhookEvent",
  "event_type": "didimo.request.completed",
  "data": {
    "__type": "Didimo",
    "__links": {
      "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a",
      "meta_data": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data",
      "favorite": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/actions/favorite",
      "unfavorite": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/actions/unfavorite"
    },
    "key": "dk56asd868edw6e54a",
    "input_type": "photo",
    "transfer_formats": [
      {
        "__type": "TransferFormat",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/results/fbx"
        },
        "name": "fbx"
      }
    ],
    "artifacts": [
      {
        "__type": "Artifact",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/artifacts/side_png"
        },
        "name": "side_png"
      },
      {
        "__type": "Artifact",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/artifacts/front_png"
        },
        "name": "front_png"
      },
      {
        "__type": "Artifact",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/artifacts/corner_png"
        },
        "name": "corner_png"
      },
      {
        "__type": "Artifact",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/artifacts/deformer_dmx"
        },
        "name": "deformer_dmx"
      }
    ],
    "percent": 100,
    "status": "done",
    "status_message": "",
    "error_code": null,
    "meta_data": [
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/api"
        },
        "name": "api",
        "value": "v3",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/generator"
        },
        "name": "generator",
        "value": "2.5.0",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/generator_uuid"
        },
        "name": "generator_uuid",
        "value": "a0871222-0f19-11ec-acbb-021254967f4f",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/tier"
        },
        "name": "tier",
        "value": "pro",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/supports-export_fbx"
        },
        "name": "supports-export_fbx",
        "value": "supports-export_fbx",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/arkit"
        },
        "name": "arkit",
        "value": "false",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/photo"
        },
        "name": "photo",
        "value": "name=depth.png;size=24649",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/aws_polly"
        },
        "name": "aws_polly",
        "value": "false",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/simple_poses"
        },
        "name": "simple_poses",
        "value": "false",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/oculus_lipsync"
        },
        "name": "oculus_lipsync",
        "value": "false",
        "definer": "system"
      },
      {
        "__type": "Metadata",
        "__links": {
          "self": "https://api.didimo.co/v3/didimos/dk56asd868edw6e54a/meta_data/max_texture_dimension"
        },
        "name": "max_texture_dimension",
        "value": "2048",
        "definer": "system"
      }
    ],
    "is_favorite": false,
    "created_at": "2021-09-07T16:10:16",
    "expires_at": "2021-10-31T23:59:59"
  },
  "context": {
    "__type": "WebhookEventContext",
    "api_key": "661ab54c-5344-4979-aab6-9e6a367233dc"
  }
}

A message is considered successfully delivered if we receive a 2xx HTTP response from your endpoint. Responses with other HTTP code ranges will be treated as errors and will lead to a retry.
Didimo will retry to send an event up to five times, with an exponential backoff. Once we hit the maximum number of tries, the event will be marked as failed and will not be sent again.

Configure your webhook endpoint on your application on Customer Portal

After creating and deploying your webhook consumer, it's time to configure it.
To do that you have to:

Login on Customer Portal;
Navigate to "Applications"
Select an existing application or create a new one;

Fill the webhook endpoint on the Webhook URL field;
Save.

You may notice that a webhook secret was automatically generated for you.

This value can be used to validate our requests on your endpoint. Each request will include this secret on an HTTP header named "didimo-webhook-secret".