Webhooks API

Overview

Webhooks are used for receiving notifications via an HTTP request whenever an event occurs in your DNSimple account.

You may register your webhook URLs either through the DNSimple web interface or through the DNSimple API. The URL must use HTTPS and the webhook handler should be able to receive HTTP POST requests.

All webhooks are sent via HTTPS using POST. It MAY occur that some webhook fire more then once. Clients MUST handle webhooks with the same request_identifier to not process them twice.

Webhooks are only supported in the DNSimple API v2 and higher.

Webhook Payload

Webhook data is sent as a JSON object in a POST request to URLs you define. All webhook messages have the same basic structure, which is called the payload:

{
  "name": "object.action",
  "api_version": "v2",
  "request_identifier": "fca1f30a-4219-4278-9272-c00e5cc2eb5c",
  "data": {},
  "account": {},
  "actor": {}
}

The name attribute contains a string representing the name of event that occurred. It will always have an object and action separated by a period. It may optionally include a state for objects that go through state changes, for example domain.registration:started.

The api_version is the API version used to serialize the data in the payload. For version 2 of the API, this is the string v2. For example, you can expect a domain object to be serialized using the same domain attributes described in the corresponding API page.

The request_identifier attribute is a UUID that provides a way to identify this request. You may use this UUID to ensure a webhook is processed once and only once by keeping a persistent history of the identifiers sent and never handling a webhook which was already processed.

The data attribute contains any data for the object or objects related to the event. Each object in the data object will be keyed on an object type name. For example:

{
  ...
  "data": {
    "domain": {
      "name": "example.com",
      ...
    }
  }
}

The account is an object describing which account the event occurred in. It is a lightweight representation of the account and includes the id, a unique identifier and a display text representation.

The actor is an object describing the entity that triggered the event. This may be a user if the event was triggered due to activity via the UI or API, or it may be a system entity if the activity occurred as part of an asynchronous process. The actor object has three attributes: id, which is a unique identifier for the actor, entity which describes what type the actor is, and pretty, which is a printable representation of the actor for use in display.

Responding to Webhooks

To confirm receipt of a webhook, your server must respond with an HTTP 200 response. Any other response will be considered an error and may cause the event to be retried.

Event List

The following events are available:

  • account.update
  • account.billing_settings_update
  • account.payment_details_update
  • account.add_user
  • account.remove_user
  • certificate.issue
  • certificate.reissue
  • certificate.remove_private_key
  • contact.create
  • contact.update
  • contact.delete
  • dnssec.create
  • dnssec.delete
  • dnssec.rotation_start
  • dnssec.rotation_complete
  • domain.auto_renewal_disable
  • domain.auto_renewal_enable
  • domain.create
  • domain.delete
  • domain.register:started
  • domain.register
  • domain.renew
  • domain.delegation_change
  • domain.registrant_change
  • domain.resolution_disable
  • domain.resolution_enable
  • domain.token_reset
  • domain.transfer:started
  • domain.transfer
  • email_forward.create
  • email_forward.delete
  • name_server.deregister
  • name_server.register
  • oauth_application.create
  • oauth_application.delete
  • oauth_application.reset_client_secret
  • oauth_application.revoke_access_tokens
  • push.accept
  • push.initiate
  • push.reject
  • secondary_dns.create
  • secondary_dns.delete
  • secondary_dns.update
  • subscription.migrate
  • subscription.subscribe
  • subscription.unsubscribe
  • template.create
  • template.delete
  • template.update
  • template_record.create
  • template_record.delete
  • vanity.disable
  • vanity.enable
  • webhook.create
  • webhook.delete
  • whois_privacy.disable
  • whois_privacy.enable
  • whois_privacy.purchase
  • whois_privacy.renew
  • zone.create
  • zone.delete
  • zone_record.create
  • zone_record.delete
  • zone_record.update

List webhooks

GET /:account/webhooks

List webhooks in the account.

Parameters

Name Type Description
:account integer The account id

Example

List all webhooks in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/webhooks

Response

Responds with HTTP 200.

{
  "data": [
    {
      "id": 1,
      "url": "https://webhook.test"
    },
    {
      "id": 2,
      "url": "https://another.test"
    }
  ]
}

Sorting

For general information about sorting, please refer to the main guide.

Name Description
id Sort webhooks by ID

The default sorting policy is by ascending id.

Create a webhook

POST /:account/webhooks

Parameters

Name Type Description
:account integer The account id

Example

Create a webhook in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '{"url":"https://test.host/handler"}' \
      https://api.dnsimple.com/v2/1010/webhooks

Input

Name Type Description
url string Required.
Example
{
  "url": "https://test.host/handler"
}

Response

Responds with HTTP 201 on success.

{
  "data": {
    "id": 1,
    "url": "https://webhook.test"
  }
}

Responds with HTTP 400 if the validation fails.

Get a webhook

GET /:account/webhooks/:webhook

Parameters

Name Type Description
:account integer The account id
:webhook integer, string The webhook id

Example

Get the webhook with ID 1 in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/webhooks/1

Response

{
  "data": {
    "id": 1,
    "url": "https://webhook.test"
  }
}

Delete a webhook

DELETE /:account/webhooks/:webhook

Parameters

Name Type Description
:account integer The account id
:webhook integer, string The webhook id

Example

Delete the webhook with ID 1 in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -X DELETE \
      https://api.dnsimple.com/v2/1010/webhooks/1

Response

Responds with HTTP 204 on success.