Your first webhook subscription

Webhooks enable you to get live status updates

In this section we guide you through the creation of your first webhook subscription on our API.

To create your first webhook with the Defacto API we will:

  • Create a webhook subscription on the Defacto REST API
  • Create a new invoice for it to trigger a status update
  • Look at the received the webhook notification

1. Create your first webhook subscription

The first step should be the creation of an endpoint on your own REST API.
However, to make this first test simpler and shorter, you can use webhook.site. It generates a callback URL specifically for you.

Copy "Your unique URL".

1440

Webhook.site

Create your first webhook subscription with POST /webhooks. For this example select the two event_types: Invoice.SUBMITTED and Invoice.VERIFIED and paste the URL from webhook.site in the to_url field.

1440

2. Create a new invoice for it to trigger a status update

3. Look at the received the webhook notification

Go back to webhook.site.

If you lost the link to your subscription, you can get it back by fetching your webhook subscriptions with GET /webhooks.

You should see two notifications. Here are the most important things to note:

  • There is one for Invoice.SUBMITTED and one for Invoice.VERIFIED
  • We call the POST method on the URL ➜ so when you will create your webhooks callbacks, make sure they listen to the POST method
  • The content uses the following data schema:
{
  "entity_type": "invoice",
  "transition_name": "SUBMIT",
  "status": "SUBMITTED",
  "timestamp": "2022-02-11T11:26:59.631326+00:00",
  "id": "a18d5057-0092-4555-b865-7ade03c3ac9b",
  "event_type": "Invoice.SUBMITTED",
  "entity_state": "<THE SAME PAYLOAD AS RETURNED BY THE GET ENDPOINT RETURNING THIS RESOURCE>"
}

Next steps

You can now create webhooks callbacks on your HTTP API. Do not forget that you must listen to the POST HTTP method.

You can create as many webhook subscription as you want. So, you can for example:

  • Create a single webhook callback
  • Create one webhook callback per status change
  • Create one webhook callback per type of resource

👍

You can also use our webhooks to get live Slack notifications!