Skip to main content

Create webhooks

Webhooks allow you to send notifications of Delivery Gateway events to a third-party service. For example, you can set up a webhook to send an event notification when a shipment is created or when a customer updates their address.

Our webhooks send a JSON payload, the content of which depends on the triggering event. One webhook is one event: create a webhook for each of the events you need to send notifications about.

Create a webhook​

Use the createWebhook mutation to create a new webhook. It creates a Webhook object.

mutation {
    createWebhook(input: {...})
    {
        id
        url
    }
}

To create a webhook, you need three inputs:

  • webhook: The event that triggers the webhook. For the full list, see WebhookEnum.
  • url: The service URL that will receive the JSON payload when an event triggers the webhook.
  • transport: The transport type. Currently, only REST is available.
mutation {
  createWebhook(
    input: {
      webhook: SHIPMENT_CREATED,
      url: "example.org",
      transport: REST,
    }
  )
  {
    id
    url
  }
}

Set a secret key for webhook signature​

We recommend setting a secret key for webhook signature. It is a shared secret used to prove that a webhook request really came from Delivery Gateway and was not tampered with in transit.

The secret key must be configured for the merchant, using the updateMerchantConfiguration mutation:

GraphQL mutation
mutation {
  updateMerchantConfiguration(
    input: {
      key: WEBHOOK_SIGNATURE
      value: Q2hhbmdlVGhpcy1Ub1JhbmRvbVNlY3JldCE=
    }
  )
  {
    key
    value
  }
}