Retrieve webhook request

curl --request GET \
  --url https://api.syntage.com/webhook-requests/{id} \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.syntage.com/webhook-requests/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.syntage.com/webhook-requests/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.syntage.com/webhook-requests/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.syntage.com/webhook-requests/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "@context": "/contexts/WebhookRequest",
  "@id": "/webhook-requests/91106968-1abd-4d64-85c1-4e73d96fb997",
  "@type": "WebhookRequest",
  "id": "e0a24894-7fbf-48ae-bfb0-efaae30a6319",
  "webhookEndpoint": {
    "@id": "/webhook-endpoints/91106968-1abd-4d64-85c1-4e73d96fb997",
    "@type": "WebhookEndpoint",
    "id": "e0a24894-7fbf-48ae-bfb0-efaae30a6319",
    "url": "https://example.com/webhooks/syntage",
    "signingSecret": "54471a278d46c86ec6cd365983552a28",
    "events": [
      "extraction.updated",
      "invoice.created"
    ],
    "enabled": true,
    "contentType": "application/ld+json",
    "createdAt": "2020-01-01T12:15:00.000Z",
    "updatedAt": "2020-01-01T12:15:00.000Z"
  },
  "url": "https://example.com/webhooks/syntage",
  "responseStatusCode": 200,
  "responseTime": 0.21983,
  "createdAt": "2020-01-01T12:15:00.000Z",
  "updatedAt": "2020-01-01T12:15:00.000Z"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Webhook Requests

Retrieve webhook request

Get a webhook delivery attempt by ID. Use the response status code, response time, related event, and endpoint details to investigate delivery behavior.

How to validate webhook calls by using the `signingSecret` value.

Whenever a webhook is called, a X-Satws-Signature header is sent to help verify it. Syntage generates a signature using a hash-based message authentication code (HMAC) with SHA-256 using the signingSecret as key. To verify the hash you can do the following steps:

Step 1: Extract the timestamp and signature from the header

Split the header, using the , character as the separator. The value for the prefix t corresponds to the timestamp and s corresponds to the signature.

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating (without spaces):

The timestamp (as a string in Unix format) example: "1656569160"
The character . (dot)
The actual JSON payload (that is, the request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance. To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

Here is a code example using PHP with a constant-time string:

    function splitString(string $separator, $stringValue): array
    {
      return explode($separator, $stringValue);
    }

    ## X-Satws-Signature
    $xSatSignatureHeader = 't=1656569160,s=527124c570b27b3f268777b2ba96a9bbdc4b0ecde2885f688beda528f39c4e23';

    list($timestamp, $signature) = array_map(function($signatureParam){
    return splitString('=', $signatureParam)[1];
    }, splitString(',', $xSatSignatureHeader));

    $bodyPayload = '{
    "@context": "/contexts/Event",
    "@id": "/events/88a88df8-5c55-44a4-a222-ef9999c999",
    "@type": "Event",
    "id": "88a88df8-5c55-44a4-a222-ef9999c999",
    "type": "credential.updated",
    "source": None,
    "createdAt": "2022-06-29 20:14:09",
    "updatedAt": "2022-06-29 20:14:09"
    }';
    $signingSecret = '320639996d9eee9178bf89d26cdbc23d';

    $hash = hash_hmac('sha256', sprintf('%d.%s', $timestamp, $bodyPayload), $signingSecret);

    print strcmp($hash, $signature);

GET

webhook-requests

{id}

Retrieve webhook request

curl --request GET \
  --url https://api.syntage.com/webhook-requests/{id} \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.syntage.com/webhook-requests/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.syntage.com/webhook-requests/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.syntage.com/webhook-requests/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.syntage.com/webhook-requests/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "@context": "/contexts/WebhookRequest",
  "@id": "/webhook-requests/91106968-1abd-4d64-85c1-4e73d96fb997",
  "@type": "WebhookRequest",
  "id": "e0a24894-7fbf-48ae-bfb0-efaae30a6319",
  "webhookEndpoint": {
    "@id": "/webhook-endpoints/91106968-1abd-4d64-85c1-4e73d96fb997",
    "@type": "WebhookEndpoint",
    "id": "e0a24894-7fbf-48ae-bfb0-efaae30a6319",
    "url": "https://example.com/webhooks/syntage",
    "signingSecret": "54471a278d46c86ec6cd365983552a28",
    "events": [
      "extraction.updated",
      "invoice.created"
    ],
    "enabled": true,
    "contentType": "application/ld+json",
    "createdAt": "2020-01-01T12:15:00.000Z",
    "updatedAt": "2020-01-01T12:15:00.000Z"
  },
  "url": "https://example.com/webhooks/syntage",
  "responseStatusCode": 200,
  "responseTime": 0.21983,
  "createdAt": "2020-01-01T12:15:00.000Z",
  "updatedAt": "2020-01-01T12:15:00.000Z"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Authorizations

X-API-Key

string

header

required

Your API key is available in the Production and Sandbox dashboards.

Path Parameters

string<uuid>

required

Response

Webhook request resource response

@context

string

default:/contexts/WebhookRequest

@id

string<iri-reference>

Webhook request IRI

Example:

"/webhook-requests/91106968-1abd-4d64-85c1-4e73d96fb997"

@type

string

default:WebhookRequest

string<uuid>

Example:

"e0a24894-7fbf-48ae-bfb0-efaae30a6319"

webhookEndpoint

object

Webhook endpoint that received the delivery attempt

Show child attributes

url

string<url>

Endpoint URL used for the delivery attempt

Example:

"https://example.com/webhooks/syntage"

responseStatusCode

integer

HTTP status code returned by the endpoint, or 0 when Syntage did not receive a response

Example:

200

responseTime

number

Delivery response time in seconds

Example:

0.21983

createdAt

string

Date and time the resource was created

Example:

"2020-01-01T12:15:00.000Z"

updatedAt

string

Date and time the resource was last updated

Example:

"2020-01-01T12:15:00.000Z"

Core Resources

Other Resources

Datasource: SAT

Datasource: RPC

Datasource: RUG

Datasource: Syntage

Datasource: Buró de Crédito

Datasource: BIL

Datasource: Infonavit

Insights

Reports

Webhooks

Retrieve webhook request

How to validate webhook calls by using the `signingSecret` value.

Step 1: Extract the timestamp and signature from the header

Step 2: Prepare the signed_payload string

Step 3: Determine the expected signature

Step 4: Compare the signatures

Here is a code example using PHP with a constant-time string:

Authorizations

Path Parameters

Response