Syntage Webhook Requests API

openapi: 3.2.0
info:
  version: '2020-06-28'
  title: Syntage Webhook Requests API
  contact:
    name: Email
    email: support@syntage.com
  description: '# Introduction


    The Syntage API is organized around REST.'
servers:
- url: https://api.syntage.com
  description: Production
- url: https://api.sandbox.syntage.com
  description: Sandbox
security:
- ApiKey: []
tags:
- name: Webhook Requests
  description: Webhook requests are delivery attempts from Syntage to a webhook endpoint. Use them to monitor delivery status, inspect failed deliveries, and connect an event to the endpoint that received it.
paths:
  /webhook-requests:
    get:
      tags:
      - Webhook Requests
      operationId: ListWebhookRequest
      description: List webhook delivery attempts for your organization.
      summary: List webhook requests
      responses:
        '200':
          $ref: '#/components/responses/WebhookRequestCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
      parameters:
      - name: url
        description: Filter by endpoint URL using exact match
        in: query
        schema:
          $ref: '#/components/schemas/WebhookRequestUrl'
      - name: responseStatusCode
        description: Filter by response status code
        in: query
        schema:
          $ref: '#/components/schemas/WebhookRequestResponseStatusCode'
      - name: event.id
        description: Filter by event ID
        in: query
        schema:
          $ref: '#/components/schemas/uuid'
      - name: event.type
        description: Filter by event type
        in: query
        schema:
          $ref: '#/components/schemas/EventType'
      - name: event.source
        description: Filter by event source
        in: query
        schema:
          $ref: '#/components/schemas/EventSource'
      - name: event.resource
        description: Filter by event resource
        in: query
        schema:
          $ref: '#/components/schemas/EventResource'
      - $ref: '#/components/parameters/collectionCursorNextPageParam'
      - $ref: '#/components/parameters/collectionCursorPreviousPageParam'
      - $ref: '#/components/parameters/collectionLimit'
  /webhook-requests/{id}:
    get:
      tags:
      - Webhook Requests
      operationId: GetWebhookRequest
      summary: Retrieve webhook request
      description: '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:

        ```php

        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);

        ```'
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          $ref: '#/components/responses/WebhookRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    WebhookRequestCollection:
      description: Webhook request collection response
      content:
        application/ld+json:
          schema:
            $ref: '#/components/schemas/WebhookRequestCollection'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    WebhookRequest:
      description: Webhook request resource response
      content:
        application/ld+json:
          schema:
            allOf:
            - type: object
              properties:
                '@context':
                  type: string
                  default: /contexts/WebhookRequest
            - $ref: '#/components/schemas/WebhookRequest'
  schemas:
    updatedAt:
      type: string
      description: Date and time the resource was last updated
      example: '2020-01-01T12:15:00.000Z'
    CollectionLimit:
      type: integer
      default: 20
      minimum: 1
      maximum: 1000
    WebhookEndpoint:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Webhook endpoint IRI
          example: /webhook-endpoints/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          default: WebhookEndpoint
        id:
          $ref: '#/components/schemas/uuid'
        url:
          $ref: '#/components/schemas/WebhookEndpointUrl'
        signingSecret:
          type: string
          description: Secret used to verify `X-Syntage-Signature` delivery headers
          example: 54471a278d46c86ec6cd365983552a28
        events:
          type: array
          example:
          - extraction.updated
          - invoice.created
          description: Event types delivered to this endpoint
          items:
            $ref: '#/components/schemas/WebhookEndpointEventType'
        enabled:
          default: true
          allOf:
          - $ref: '#/components/schemas/WebhookEndpointEnabled'
        contentType:
          default: application/ld+json
          anyOf:
          - $ref: '#/components/schemas/WebhookEndpointContentType'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    WebhookEndpointUrl:
      type: string
      format: url
      description: Public HTTPS URL where Syntage sends matching webhook events
      example: https://example.com/webhooks/syntage
    WebhookRequestUrl:
      type: string
      format: url
      description: Endpoint URL used for the delivery attempt
      example: https://example.com/webhooks/syntage
    EventType:
      type: string
      enum:
      - credential.created
      - credential.updated
      - credential.deleted
      - link.created
      - link.updated
      - link.deleted
      - file.created
      - extraction.created
      - extraction.updated
      - invoice.created
      - invoice.updated
      - invoice.deleted
      - invoice_payment.created
      - invoice_payment.updated
      - invoice_line_item.created
      - invoice_line_item.updated
      - tax_return.created
      - tax_return.updated
      - tax_return.deleted
      - export.created
      - export.updated
      - tax_status.created
      - tax_status.updated
      - tax_status.deleted
      - tax_compliance_check.created
      - tax_compliance_check.updated
      - tax_compliance_check.deleted
      - tax_retention.created
      - tax_retention.updated
      - tax_retention.deleted
      - electronic_accounting_record.created
      - electronic_accounting_record.updated
      - electronic_accounting_record.deleted
      - rpc_entidades.created
      - rpc_entidades.updated
      - rpc_acto.created
      - rpc_acto.updated
      - rpc_socios.created
      - rpc_socios.updated
      - shareholder_relation.created
      - shareholder_relation.updated
      - shareholder_relation_source.created
      - rug_garantia.created
      - rug_garantia.updated
      - buro_de_credito_report.created
      - buro_de_credito_report.updated
      - sat_certificate.created
      - sat_certificate.updated
      - background_check.created
      - company_verification_report.created
      - company_verification_report.updated
      example: credential.updated
    CursorCollection:
      type: object
      properties:
        '@context':
          type: string
        '@id':
          type: string
        '@type':
          type: string
          default: hydra:Collection
        hydra:member:
          type: array
          items:
            type: object
        hydra:view:
          type: object
          description: Pagination information
          properties:
            '@id':
              type: string
              format: iri-reference
              description: Current page IRI reference
            '@type':
              type: string
              default: hydra:PartialCollectionView
            hydra:next:
              type: string
              example: /entity/2a15f539-3251-48e1-aaeb-a154dc9c6edb/resource?id[lt]=9b8e5365-0b36-45f5-9c76-fbe439632367
              description: Next page IRI reference; omitted when there is no pagination
            hydra:last:
              type: string
              example: /entity/2a15f539-3251-48e1-aaeb-a154dc9c6edb/resource?id[gt]=9b8e5365-0b36-45f5-9c76-fbe439632367
              description: Last page IRI reference; omitted when there is no pagination
        hydra:search:
          type: object
          properties:
            '@type':
              type: string
            hydra:template:
              type: string
            hydra:variableRepresentation:
              type: string
            hydra:mapping:
              type: array
              items:
                type: object
                properties:
                  '@type':
                    type: string
                  variable:
                    type: string
                  property:
                    type: string
                  required:
                    type: boolean
    EventResource:
      type: string
      format: iri-reference
      description: Resource related to the event
      example: /credentials/91106968-1abd-4d64-85c1-4e73d96fb997
    WebhookEndpointContentType:
      type: string
      description: Content type used for webhook delivery payloads
      enum:
      - application/ld+json
      - application/json
    WebhookRequest:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Webhook request IRI
          example: /webhook-requests/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          default: WebhookRequest
        id:
          $ref: '#/components/schemas/uuid'
        webhookEndpoint:
          description: Webhook endpoint that received the delivery attempt
          $ref: '#/components/schemas/WebhookEndpoint'
        url:
          $ref: '#/components/schemas/WebhookRequestUrl'
        responseStatusCode:
          $ref: '#/components/schemas/WebhookRequestResponseStatusCode'
        responseTime:
          type: number
          description: Delivery response time in seconds
          example: 0.21983
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    EventSource:
      type: string
      format: iri-reference
      description: Source that originated the event
      example: /extractions/91106968-1abd-4d64-85c1-4e73d96fb997
    WebhookEndpointEventType:
      type: string
      description: Event type delivered to a webhook endpoint
      enum:
      - credential.created
      - credential.updated
      - credential.deleted
      - link.created
      - link.updated
      - link.deleted
      - extraction.created
      - extraction.updated
      - invoice.created
      - invoice.updated
      - invoice.deleted
      - tax_return.created
      - tax_return.updated
      - tax_return.deleted
      - file.created
      - export.created
      - export.updated
      - tax_status.created
      - tax_status.updated
      - tax_status.deleted
      - tax_compliance_check.created
      - tax_compliance_check.updated
      - tax_compliance_check.deleted
      - tax_retention.created
      - tax_retention.updated
      - tax_retention.deleted
      - invoice_payment.created
      - invoice_payment.updated
      - invoice_line_item.created
      - invoice_line_item.updated
      - electronic_accounting_record.created
      - electronic_accounting_record.updated
      - rpc_entidades.created
      - rpc_entidades.updated
      - rpc_socios.created
      - rpc_socios.updated
      - rpc_acto.created
      - rpc_acto.updated
      - shareholder_relation.created
      - shareholder_relation.updated
      - shareholder_relation_source.created
      - rug_garantia.created
      - rug_garantia.updated
      - buro_de_credito_report.created
      - buro_de_credito_report.updated
      - background_check.created
      - sat_certificate.created
      - sat_certificate.updated
      - company_verification_report.created
      - company_verification_report.updated
    WebhookEndpointEnabled:
      type: boolean
      example: true
      description: Whether Syntage sends matching events to this endpoint
    createdAt:
      type: string
      description: Date and time the resource was created
      example: '2020-01-01T12:15:00.000Z'
    WebhookRequestResponseStatusCode:
      type: integer
      description: HTTP status code returned by the endpoint, or `0` when Syntage did not receive a response
      example: 200
    WebhookRequestCollection:
      allOf:
      - $ref: '#/components/schemas/CursorCollection'
      - type: object
        properties:
          '@context':
            default: /contexts/WebhookRequest
          '@id':
            default: /webhook-requests
          hydra:member:
            items:
              $ref: '#/components/schemas/WebhookRequest'
    uuid:
      type: string
      format: uuid
      example: e0a24894-7fbf-48ae-bfb0-efaae30a6319
  parameters:
    resourceId:
      name: id
      in: path
      required: true
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      schema:
        type: string
        format: uuid
    collectionCursorPreviousPageParam:
      name: id[gt]
      in: query
      required: false
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      description: Collection cursor pointer to the previous page
      schema:
        type: string
    collectionLimit:
      name: itemsPerPage
      in: query
      required: false
      description: Number of items per page
      schema:
        $ref: '#/components/schemas/CollectionLimit'
    collectionCursorNextPageParam:
      name: id[lt]
      in: query
      required: false
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      description: Collection cursor pointer to the next page
      schema:
        type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Your API key is available in the [Production](https://app.syntage.com/settings/api-keys) and [Sandbox](https://app.sandbox.syntage.com/settings/api-keys) dashboards.

        '
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true